@orkestrel/scaffold 0.0.124 → 0.0.126

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 (53) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
  3. package/dist/bin/main.js +51 -18
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +7 -2
  6. package/dist/host/agents/platforms/windows.md +9 -1
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +1 -1
  9. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +32 -4
  11. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +18 -19
  12. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +2 -1
  14. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
  15. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
  16. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  17. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
  18. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
  19. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
  20. package/dist/host/claude/agents/orkestrel.md +28 -28
  21. package/dist/host/claude/rules/patterns.md +1 -1
  22. package/dist/host/claude/rules/portability.md +2 -0
  23. package/dist/host/claude/rules/quality.md +6 -1
  24. package/dist/host/claude/rules/tests.md +6 -1
  25. package/dist/host/claude/rules/workspace.md +8 -3
  26. package/dist/host/guides/agent.md +575 -346
  27. package/dist/host/guides/brief.md +52 -48
  28. package/dist/host/guides/browser.md +2 -2
  29. package/dist/host/guides/interpret.md +531 -155
  30. package/dist/host/guides/mcp.md +183 -61
  31. package/dist/host/guides/ndjson.md +4 -3
  32. package/dist/host/guides/ollama.md +125 -68
  33. package/dist/host/guides/program.md +117 -39
  34. package/dist/host/guides/qualifier.md +110 -59
  35. package/dist/host/guides/rater.md +85 -32
  36. package/dist/host/guides/scaffold.md +49 -22
  37. package/dist/host/guides/study.md +596 -489
  38. package/dist/host/guides/toolbox.md +159 -80
  39. package/dist/host/guides/workflow.md +44 -25
  40. package/dist/host/manifest.json +41 -35
  41. package/dist/src/core/index.cjs +12 -10
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.d.cts +3 -1
  44. package/dist/src/core/index.d.ts +3 -1
  45. package/dist/src/core/index.js +12 -10
  46. package/dist/src/core/index.js.map +1 -1
  47. package/dist/src/server/index.cjs +23 -11
  48. package/dist/src/server/index.cjs.map +1 -1
  49. package/dist/src/server/index.d.cts +10 -6
  50. package/dist/src/server/index.d.ts +10 -6
  51. package/dist/src/server/index.js +23 -11
  52. package/dist/src/server/index.js.map +1 -1
  53. package/package.json +7 -7
@@ -5,7 +5,7 @@
5
5
  // that fails: pin (read `scaffold audit --json`, whose drift exit is the reading the pin closes, then
6
6
  // re-pin every range the audit release readings name to the registry caret and install), commit (`git commit --only` of
7
7
  // the manifest and lockfile as the preparation commit), overwrite (`scaffold overwrite --json`, then
8
- // `scaffold audit` exiting 0; offline, an exit of 1 whose note names the catalog refusal is
8
+ // `scaffold audit` exiting 0; offline, an exit of 1 whose note names the skipped catalog step is
9
9
  // accepted; on @orkestrel/scaffold itself both are skipped with a note, because the vendored host
10
10
  // is staged from that checkout), verify (`scaffold audit --json` prints the releases envelope and
11
11
  // the audit's writable dependency population matches its lookup bounds; on @orkestrel/scaffold itself an audit exit of 1 is
@@ -68,8 +68,20 @@ export const RANGE_FIELDS: readonly string[] = [...RUNTIME_FIELDS, 'devDependenc
68
68
  /** Names the agent file that carries the catalog table. */
69
69
  export const CATALOG = '.claude/agents/orkestrel.md'
70
70
 
71
- /** Holds the text an offline overwrite refusal names. */
72
- export const OFFLINE_REFUSAL = "'catalog' does not take --offline"
71
+ /**
72
+ * Lists the texts that name the catalog step an offline overwrite skips.
73
+ *
74
+ * @remarks
75
+ * The executable is the target's installed release, so a checkout's script also reads the wording an
76
+ * earlier release prints.
77
+ */
78
+ export const OFFLINE_NOTES: readonly string[] = [
79
+ 'the catalog reads upstream and --offline reads none',
80
+ "'catalog' does not take --offline",
81
+ ]
82
+
83
+ /** Lists the codes a host reports when a process holds a file a move or a removal reaches. */
84
+ export const HELD_CODES: readonly string[] = ['EBUSY', 'EPERM']
73
85
 
74
86
  /**
75
87
  * Names the package whose checkout the vendored host is staged from.
@@ -668,14 +680,14 @@ export function judgePin(result: SpawnSyncReturns<string>): Verdict {
668
680
  * Judges the overwrite command.
669
681
  *
670
682
  * @param result - The overwrite.
671
- * @param offline - If `true`, an exit of 1 whose note names the catalog refusal passes; if `false`,
672
- * the exit alone decides.
683
+ * @param offline - If `true`, an exit of 1 whose note names the skipped catalog step passes; if
684
+ * `false`, the exit alone decides.
673
685
  * @returns The verdict.
674
686
  */
675
687
  export function judgeOverwrite(result: SpawnSyncReturns<string>, offline: boolean): Verdict {
676
688
  if (!offline || result.status !== 1) return readVerdict(result)
677
689
  const note = readString(parseJsonLine(result.stdout), 'note')
678
- return note !== undefined && note.includes(OFFLINE_REFUSAL)
690
+ return note !== undefined && OFFLINE_NOTES.some((text) => note.includes(text))
679
691
  ? { exit: 0, note: 'offline overwrite skipped the catalog step by design' }
680
692
  : { exit: 1, note: describeFailure(result) }
681
693
  }
@@ -1001,6 +1013,18 @@ export function readRegenerationRefusal(runner: Runner): string | undefined {
1001
1013
  return undefined
1002
1014
  }
1003
1015
 
1016
+ /**
1017
+ * Extracts the code that names a held file from a thrown value.
1018
+ *
1019
+ * @param error - The thrown value.
1020
+ * @returns The code when {@link HELD_CODES} lists it, else undefined.
1021
+ */
1022
+ export function extractHeldCode(error: unknown): string | undefined {
1023
+ return isRecord(error) && typeof error.code === 'string' && HELD_CODES.includes(error.code)
1024
+ ? error.code
1025
+ : undefined
1026
+ }
1027
+
1004
1028
  /**
1005
1029
  * Renames a directory, retrying while the host holds it.
1006
1030
  *
@@ -1014,8 +1038,7 @@ export function moveModules(source: string, target: string, attempt = 0): void {
1014
1038
  try {
1015
1039
  renameSync(source, target)
1016
1040
  } catch (error) {
1017
- if (!isRecord(error) || (error.code !== 'EBUSY' && error.code !== 'EPERM') || attempt >= 9)
1018
- throw error
1041
+ if (extractHeldCode(error) === undefined || attempt >= 9) throw error
1019
1042
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
1020
1043
  moveModules(source, target, attempt + 1)
1021
1044
  }
@@ -1092,10 +1115,15 @@ export function regenerateLock(
1092
1115
  runner,
1093
1116
  step,
1094
1117
  'regenerate lock and modules',
1095
- [result.note, restored, versions === undefined ? undefined : `installed ${versions}`, cleanup]
1118
+ [
1119
+ result.note,
1120
+ restored,
1121
+ versions === undefined ? undefined : `installed ${versions}`,
1122
+ cleanup?.note,
1123
+ ]
1096
1124
  .filter((value) => value !== undefined)
1097
1125
  .join('; '),
1098
- cleanup === undefined ? result.exit : 1,
1126
+ cleanup?.exit ?? result.exit,
1099
1127
  )
1100
1128
  if (result.installed !== undefined)
1101
1129
  appendResult(
@@ -1152,18 +1180,55 @@ export function regenerateTree(target: string, manifest: Buffer, before: string)
1152
1180
  * @param target - The target directory.
1153
1181
  * @param moved - The moved previous tree.
1154
1182
  * @param backup - The saved lock.
1155
- * @returns Nothing on success, else the failure with the backup paths kept.
1183
+ * @returns Exit 0 and no note on success, else the verdict {@link judgeCleanup} reaches.
1156
1184
  */
1157
- export function discardBackup(target: string, moved: string, backup: string): string | undefined {
1185
+ export function discardBackup(target: string, moved: string, backup: string): Verdict {
1158
1186
  try {
1159
1187
  for (const path of [moved, backup, join(target, 'node_modules')]) validateWavePath(target, path)
1188
+ } catch (error) {
1189
+ return judgeCleanup(error, false, backup, moved)
1190
+ }
1191
+ try {
1160
1192
  removeTree(moved)
1161
- return undefined
1193
+ return { exit: 0, note: undefined }
1162
1194
  } catch (error) {
1163
- return `backup cleanup failed: ${String(error)}; proved installation retained; backups: ${backup}; ${moved}`
1195
+ return judgeCleanup(error, true, backup, moved)
1164
1196
  }
1165
1197
  }
1166
1198
 
1199
+ /**
1200
+ * Judges a cleanup that failed after a proved regeneration.
1201
+ *
1202
+ * @remarks
1203
+ * The proved installation reads nothing from the moved tree, so a file a process holds there stops
1204
+ * neither the step nor the visit.
1205
+ *
1206
+ * @param failure - The thrown value.
1207
+ * @param removing - If `true`, the removal threw and a held file's code passes; if `false`, the path
1208
+ * validation threw and every value fails.
1209
+ * @param backup - The saved lock.
1210
+ * @param moved - The moved previous tree.
1211
+ * @returns Exit 0 with a note that names the code for a held file, else exit 1; each note names both
1212
+ * backup paths.
1213
+ */
1214
+ export function judgeCleanup(
1215
+ failure: unknown,
1216
+ removing: boolean,
1217
+ backup: string,
1218
+ moved: string,
1219
+ ): Verdict {
1220
+ const code = removing ? extractHeldCode(failure) : undefined
1221
+ return code === undefined
1222
+ ? {
1223
+ exit: 1,
1224
+ note: `backup cleanup failed: ${String(failure)}; proved installation retained; backups: ${backup}; ${moved}`,
1225
+ }
1226
+ : {
1227
+ exit: 0,
1228
+ note: `proved installation retained; a held file stopped backup cleanup (${code}): ${String(failure)}; backups: ${backup}; ${moved}`,
1229
+ }
1230
+ }
1231
+
1167
1232
  /**
1168
1233
  * Restores the previous tree and lock after a failed regeneration.
1169
1234
  *
@@ -44,57 +44,57 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
44
44
  | Package | Version | Layer | Runtime dependencies | Peer dependencies |
45
45
  | ----------------------- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
46
46
  | `@orkestrel/abort` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
47
- | `@orkestrel/agent` | `0.0.35` | L5 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/abort` `^0.0.15`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/ndjson` `^0.0.15`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20`, `@orkestrel/workflow` `^0.0.25`, `@orkestrel/workspace` `^0.0.14` | |
48
- | `@orkestrel/brief` | `0.0.14` | L4 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/interpret` `^0.0.19` | |
49
- | `@orkestrel/browser` | `0.0.31` | L5 | `@orkestrel/mcp` `^0.0.41`, `@orkestrel/html` `^0.0.14`, `@orkestrel/pool` `^0.0.19`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/router` `^0.0.19`, `@orkestrel/server` `^0.0.25`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19`, `@orkestrel/websocket` `^0.0.17` | |
47
+ | `@orkestrel/agent` | `0.0.38` | L5 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/abort` `^0.0.16`, `@orkestrel/queue` `^0.0.20`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ndjson` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21`, `@orkestrel/workflow` `^0.0.26`, `@orkestrel/workspace` `^0.0.15` | |
48
+ | `@orkestrel/brief` | `0.0.17` | L4 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/interpret` `^0.0.22` | |
49
+ | `@orkestrel/browser` | `0.0.32` | L5 | `@orkestrel/mcp` `^0.0.42`, `@orkestrel/html` `^0.0.15`, `@orkestrel/pool` `^0.0.20`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/websocket` `^0.0.18` | |
50
50
  | `@orkestrel/budget` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
51
- | `@orkestrel/capture` | `0.0.3` | L3 | `@orkestrel/process` `^0.0.17`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `vite` `^8.3.5`, `vitest` `^4.1.12 \|\| ^5.0.5`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
51
+ | `@orkestrel/capture` | `0.0.4` | L3 | `@orkestrel/process` `^0.0.18`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `vite` `^8.3.6`, `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
52
52
  | `@orkestrel/codec` | `0.0.9` | L1 | `@orkestrel/contract` `^0.0.22` | |
53
53
  | `@orkestrel/console` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
54
54
  | `@orkestrel/contract` | `0.0.22` | L0 | | |
55
- | `@orkestrel/csv` | `0.0.12` | L2 | `@orkestrel/codec` `^0.0.8`, `@orkestrel/contract` `^0.0.21` | |
55
+ | `@orkestrel/csv` | `0.0.13` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
56
56
  | `@orkestrel/database` | `0.0.21` | L2 | `@orkestrel/sqlite` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/indexeddb` `^0.0.17` | |
57
57
  | `@orkestrel/emitter` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.22` | |
58
58
  | `@orkestrel/form` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
59
- | `@orkestrel/guide` | `0.0.29` | L3 | `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19` | |
59
+ | `@orkestrel/guide` | `0.0.30` | L3 | `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20` | |
60
60
  | `@orkestrel/html` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.22` | |
61
61
  | `@orkestrel/indexeddb` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
62
- | `@orkestrel/interpret` | `0.0.19` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/template` `^0.0.12` | |
62
+ | `@orkestrel/interpret` | `0.0.22` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/template` `^0.0.13` | |
63
63
  | `@orkestrel/jsonrpc` | `0.0.2` | L1 | `@orkestrel/contract` `^0.0.22` | |
64
- | `@orkestrel/lsp` | `0.0.13` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/jsonrpc` `^0.0.1`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
64
+ | `@orkestrel/lsp` | `0.0.14` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
65
65
  | `@orkestrel/markdown` | `0.0.20` | L2 | `@orkestrel/html` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
66
- | `@orkestrel/mcp` | `0.0.41` | L4 | `@orkestrel/sse` `^0.0.12`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/jsonrpc` `^0.0.1`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/websocket` `^0.0.17` | `@orkestrel/router` `^0.0.19`, `@orkestrel/server` `^0.0.25` |
67
- | `@orkestrel/middleware` | `0.0.27` | L4 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `@orkestrel/server` `^0.0.25`, `@orkestrel/database` `^0.0.20` |
68
- | `@orkestrel/msg` | `0.0.15` | L2 | `@orkestrel/codec` `^0.0.8`, `@orkestrel/contract` `^0.0.21` | |
66
+ | `@orkestrel/mcp` | `0.0.42` | L4 | `@orkestrel/sse` `^0.0.13`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/websocket` `^0.0.18` | `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26` |
67
+ | `@orkestrel/middleware` | `0.0.28` | L4 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `@orkestrel/server` `^0.0.26`, `@orkestrel/database` `^0.0.21` |
68
+ | `@orkestrel/msg` | `0.0.16` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
69
69
  | `@orkestrel/ndjson` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
70
- | `@orkestrel/ollama` | `0.0.29` | L6 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/agent` `^0.0.35`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/ndjson` `^0.0.15`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
70
+ | `@orkestrel/ollama` | `0.0.32` | L6 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/agent` `^0.0.38`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ndjson` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
71
71
  | `@orkestrel/pool` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
72
- | `@orkestrel/probe` | `0.0.28` | L5 | `@orkestrel/lsp` `^0.0.13`, `@orkestrel/mcp` `^0.0.41`, `@orkestrel/pool` `^0.0.19`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `vitest` `^4.1.12 \|\| ^5.0.5`, `typescript` `^6.0.3 \|\| ^7.0.2` |
72
+ | `@orkestrel/probe` | `0.0.29` | L5 | `@orkestrel/lsp` `^0.0.14`, `@orkestrel/mcp` `^0.0.42`, `@orkestrel/pool` `^0.0.20`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `vitest` `^4.1.12 \|\| ^5.1.0`, `typescript` `^6.0.3 \|\| ^7.0.2` |
73
73
  | `@orkestrel/process` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
74
- | `@orkestrel/program` | `0.0.19` | L4 | `@orkestrel/rater` `^0.0.20`, `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/qualifier` `^0.0.20` | |
75
- | `@orkestrel/qualifier` | `0.0.20` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
76
- | `@orkestrel/queue` | `0.0.19` | L3 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
77
- | `@orkestrel/rater` | `0.0.20` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
74
+ | `@orkestrel/program` | `0.0.20` | L4 | `@orkestrel/rater` `^0.0.21`, `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/qualifier` `^0.0.21` | |
75
+ | `@orkestrel/qualifier` | `0.0.21` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
76
+ | `@orkestrel/queue` | `0.0.20` | L3 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
77
+ | `@orkestrel/rater` | `0.0.21` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
78
78
  | `@orkestrel/reason` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
79
- | `@orkestrel/relation` | `0.0.18` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
79
+ | `@orkestrel/relation` | `0.0.19` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
80
80
  | `@orkestrel/router` | `0.0.20` | L2 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
81
- | `@orkestrel/scaffold` | `0.0.123` | L3 | `@orkestrel/console` `^0.0.18`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19`, `@orkestrel/template` `^0.0.12` | |
82
- | `@orkestrel/sea` | `0.0.21` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
83
- | `@orkestrel/server` | `0.0.25` | L3 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/router` `^0.0.19`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | |
81
+ | `@orkestrel/scaffold` | `0.0.125` | L3 | `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/template` `^0.0.13` | |
82
+ | `@orkestrel/sea` | `0.0.22` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
83
+ | `@orkestrel/server` | `0.0.26` | L3 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | |
84
84
  | `@orkestrel/sqlite` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
85
85
  | `@orkestrel/sse` | `0.0.13` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
86
- | `@orkestrel/study` | `0.0.10` | L7 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/abort` `^0.0.15`, `@orkestrel/agent` `^0.0.35`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/ollama` `^0.0.29`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | |
87
- | `@orkestrel/table` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
86
+ | `@orkestrel/study` | `0.0.15` | L7 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/abort` `^0.0.16`, `@orkestrel/agent` `^0.0.38`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ollama` `^0.0.32`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | |
87
+ | `@orkestrel/table` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
88
88
  | `@orkestrel/template` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
89
- | `@orkestrel/terminal` | `0.0.22` | L3 | `@orkestrel/sse` `^0.0.12`, `@orkestrel/form` `^0.0.15`, `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
89
+ | `@orkestrel/terminal` | `0.0.23` | L3 | `@orkestrel/sse` `^0.0.13`, `@orkestrel/form` `^0.0.16`, `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
90
90
  | `@orkestrel/test` | `0.0.33` | L1 | `@orkestrel/contract` `^0.0.22` | `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.64.1` |
91
91
  | `@orkestrel/timeout` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
92
92
  | `@orkestrel/tool` | `0.0.22` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
93
- | `@orkestrel/toolbox` | `0.0.24` | L6 | `@orkestrel/form` `^0.0.15`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/agent` `^0.0.35`, `@orkestrel/server` `^0.0.25`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20`, `@orkestrel/relation` `^0.0.18`, `@orkestrel/terminal` `^0.0.22`, `@orkestrel/workflow` `^0.0.25`, `@orkestrel/workspace` `^0.0.14` | |
93
+ | `@orkestrel/toolbox` | `0.0.27` | L6 | `@orkestrel/form` `^0.0.16`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/agent` `^0.0.38`, `@orkestrel/server` `^0.0.26`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21`, `@orkestrel/relation` `^0.0.19`, `@orkestrel/terminal` `^0.0.23`, `@orkestrel/workflow` `^0.0.26`, `@orkestrel/workspace` `^0.0.15` | |
94
94
  | `@orkestrel/websocket` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
95
- | `@orkestrel/worker` | `0.0.19` | L4 | `@orkestrel/pool` `^0.0.19`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
96
- | `@orkestrel/workflow` | `0.0.25` | L4 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
97
- | `@orkestrel/workspace` | `0.0.14` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
95
+ | `@orkestrel/worker` | `0.0.20` | L4 | `@orkestrel/pool` `^0.0.20`, `@orkestrel/queue` `^0.0.20`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
96
+ | `@orkestrel/workflow` | `0.0.26` | L4 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/queue` `^0.0.20`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
97
+ | `@orkestrel/workspace` | `0.0.15` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.21` | |
98
98
 
99
99
  <!-- /orkestrel:catalog -->
100
100
 
@@ -139,7 +139,7 @@ Use these orthogonal contract mechanisms:
139
139
  - Report unread or unavailable evidence as unread, never as a false predicate or an empty success.
140
140
  - Bind admission and approval to the exact operation and instance, and recheck that binding across every suspension and callback before dispatch.
141
141
  - Name the actual commit boundary in a restore or continuation claim, partial commits included.
142
- - Declare a parser's whole admitted language and its adjacent refusals, and prove them with a table of the class; never tune the parser example by example.
142
+ - Declare a parser's whole admitted language and its adjacent refusals, and prove them with a table of the class; never tune the parser example by example. On a parser change, run a seeded differential against its parent build, and read a passing suite as no evidence of what the change moved.
143
143
  - Derive a decision from validated inputs; an editable prior result never substitutes for them.
144
144
  - Project a value outward by its authorship and trust origin, and accept no authority channel from a client.
145
145
 
@@ -35,6 +35,8 @@ and the form of a conditional skip.
35
35
  - Split arrived text on `/\r\n|\n/`. Never split on `\n` alone, and never split on a bare `\r`.
36
36
  - Split first, then trim each line; trimming the whole payload leaves a `\r` on every line but the
37
37
  last.
38
+ - Split `git status --porcelain` output before reading its columns, or read the `-z` form: trimming
39
+ the whole output eats the first row's leading status column, and a fixed slice then cuts its path.
38
40
  - Frame a named protocol — HTTP, LSP, RFC 6455, NDJSON — with the terminator that protocol fixes,
39
41
  and leave that terminator alone.
40
42
  - Emit `\n` from code this package owns. Never emit `os.EOL`.
@@ -29,6 +29,7 @@ These rules govern how a claim is established: the evidence read before a change
29
29
  - A clean reproduction of a reported defect means your input was weaker than the reporter's; get theirs before ruling. An input the compiler rejects refutes that input, not the finding.
30
30
  - "No tests found", an empty match, or a runner that resolved nothing reports on the harness. Confirm the probe was collected before reading a result.
31
31
  - Prefer an observation to a derivation. When a measurement and an argument disagree, the argument is wrong until the measurement is shown broken.
32
+ - When a probe compares a candidate with its base, extract the base with the `git archive` command into its own tree under `tmp/probes/`, link the checkout's `node_modules` directory into that tree, run the same probe in both trees, and read each arm from the JSON file it writes.
32
33
  - Read a gate bare. A `| tail` or `| grep` behind it hides the failing lines and reports the pipe's exit code.
33
34
 
34
35
  ## Instruments
@@ -45,6 +46,7 @@ These rules govern how a claim is established: the evidence read before a change
45
46
  - Read a receipt as evidence about its claim, never as a gate result.
46
47
  - State the instrument's coverage beside its result. Match the instrument to the question: a text search reports on text; a claim about declarations or call sites needs the compiler or a parser.
47
48
  - Report a question unanswered rather than answering it with a weaker instrument.
49
+ - When a verdict reads rows or numbers, refuse the verdict on an empty result or on a missing or non-finite number; never read either as zero or as a pass.
48
50
  - Baseline a published-artifact claim against the published artifact (the tarball, the deployed asset). Prove a module cycle by loading the built entry points.
49
51
  - Promote an instrument that settled a claim into a test, with its control, before accepting the work it settled.
50
52
 
@@ -55,8 +57,11 @@ These rules govern how a claim is established: the evidence read before a change
55
57
  - Refuse a micro optimization (hoisting a small array, caching one cheap read, shaving a constant) unless its own measurement shows a gain worth having.
56
58
  - Keep an algorithmic repair (a superlinear term, a repeated layout) when the measurement shows it.
57
59
  - Before the run, size the fixtures, the sample count, and the threshold to the case, and state the reasoning and the result that makes the change worth keeping.
60
+ - Before setting a floor on a quality or cost reading, read the spread its setting shows under a small unrelated change, and set the floor outside that spread.
58
61
  - Read the difference between methods against each side's reported uncertainty, and record no difference smaller than the result stated before the run.
59
- - Report every measurement with the host's other load during the run.
62
+ - Report every measurement with the host's other load during the run, its memory and console counts included.
63
+ - When a brief changes a hot path, name a measured cost bar at the input limit, and read the cost there before acceptance: an ordinary-length test cannot read a superlinear term.
64
+ - Before a long measured run, rehearse it at full scale on its real inputs with the model or service taken out, and read the rehearsal's own cost, before spending the window. A review or a hand fixture does not stand in for that rehearsal.
60
65
  - Compare two builds interleaved in one run under one host load, with `.agents/skills/orkestrel-harden/scripts/interleave.ts`. Read a published side from the published artifact, calibrate the run with identical sides, and bar the relative change, never an absolute reading from another moment.
61
66
  - Price a cost over the caller's whole lifecycle and workload: construction, restoration, transfer, and decision beside the warm saving.
62
67
  - Derive a cost stop from what the consumer spends around the cost, and state responsiveness and throughput as separate claims.
@@ -37,11 +37,13 @@ These rules govern what a test asserts and where it lives, the cross-cutting and
37
37
  - Use recorders for calls/events, temporary resources for stateful boundaries, protocol-faithful fixture servers for deterministic network peers, and the real external service when its behavior is the claim.
38
38
  - Prefer inert customizable data and input stubs.
39
39
  - Allow a scripted boundary stub only when it implements the real interface or protocol minimally, to drive the system under test. It never reimplements project-owned behavior and never stands in for the integration being claimed.
40
+ - When a dependency's release changes a wire a scripted boundary stub serves, update the stub to the wire as the dependency sends it, and keep every caller-facing assertion.
40
41
  - Bind a test fixture server to `127.0.0.1` on an ephemeral port (`listen(0)`), never to `::1` and never to a fixed port: a host without IPv6 fails `EAFNOSUPPORT`, and a fixed port flakes on occupancy.
41
42
  - Cover happy paths, error paths, empty input, boundary values, `NaN`, positive/negative zero, cycles, and Map/Set order where relevant.
42
43
  - Test observable behavior, not implementation details.
43
44
  - Assert the membership a discovered or globbed set must have, not a total that a partly empty population satisfies. A glob spanning two locations passes a size check while one of them matches nothing.
44
45
  - Never assert an implementation against itself. Compare the answer to a declaration, a fixture, or a second mechanism that could disagree with it. Re-deriving the answer the same way the source derives it produces a test that passes for every value the source ever returns, and it reads exactly like a real one.
46
+ - When two mechanisms agree, also drive the real harness's call to them on an input whose answer is known: their parity reads neither one's call site.
45
47
  - Probe a host-varying property at runtime, on the host the test is running on, and assert against what the probe returned. Filesystem case folding, path separators, permission bits, and rename semantics differ per host, and a thrown error's class or message differs per Node major, so a fixture built on one host describes that host and silently measures something else on the next.
46
48
  - 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.
47
49
  - 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.
@@ -277,7 +279,9 @@ Import `waitForCondition`, `waitForEvent`, `waitForAbort`, and `retryUntil` from
277
279
  event in a test or a setup module is a defect: `waitForCondition` owns the poll, `waitForEvent`
278
280
  the deferred on an event, and `waitForAbort` the deferred on a signal. A guide fence transcribed
279
281
  byte for byte into `tests/guides.test.ts` is the consumer's code and stays as the guide shows it.
280
- Give each timed wait a `description` the timeout error names.
282
+ Give each timed wait a `description` the timeout error names. When a poll fails, read what it saw
283
+ along the way before ruling on its final reading, and let a background start's rejection reach the
284
+ wait through its signal rather than swallowing it with an empty `catch`.
281
285
 
282
286
  ### Scratch
283
287
 
@@ -345,6 +349,7 @@ Before accepting that a behavior cannot be tested, look for the seam that would
345
349
 
346
350
  - Treat a collaborator reached through a hard-coded global — a stream, a clock source, a spawn, a fetch — as a missing injection point, not an untestable truth.
347
351
  - An injected collaborator with a real minimal implementation is a sanctioned boundary stub, not a mock of project-owned behavior.
352
+ - When a recording replays a wire, keep run-local identity, such as a random id or a clock reading, off it: after reading on the real peer that it treats the field as a label, send a key every run sends alike, such as the item's position, and map the answers back at the caller.
348
353
  - Add the seam rather than shipping the gap whenever the design would welcome it anyway, and whenever a sibling collaborator is already injected.
349
354
  - Record a genuinely irreducible gap where a reader meets it: what is unproven, why it cannot be driven, and what would change that. A silent untested guard reads exactly like a tested one.
350
355
 
@@ -185,7 +185,7 @@ one environment, so each is its own project:
185
185
  | `config` | `tests/config.test.ts` | Root configuration resolves its aliases, projects, and outputs, and the `configs/` leaves behind them | `test` |
186
186
  | `setup` | `tests/setup*.test.ts` other than either `setup:browser` proof | Prove root setup behavior in Node with `setup.ts`. | `test` |
187
187
  | `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` |
188
- | `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 |
188
+ | `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`. | On demand; `test` when private |
189
189
  | `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` |
190
190
  | `conformance` | `tests/conformance.test.ts` | Where this package drifts from the official tooling it tracks | `test` |
191
191
  | `tree` | `tests/tree.test.ts` | The laws this package states about its own real tree that no vendored proof carries | `test` |
@@ -215,8 +215,8 @@ one environment, so each is its own project:
215
215
  factory, which resolves the Vite mode to `browser` or an app-side browser extension and collects
216
216
  `tests/app/<application>/integration.test.ts` for that application. The factory merges its
217
217
  `override` last, through `mergeOverride`, so an override replaces nothing it does not name. Exclude each collected suite
218
- from its application project, and run `test:journey` and one `test:journey:<framework>` per
219
- app-side browser extension after the application projects in `test`.
218
+ from its application project. Generate `test:journey` and one `test:journey:<framework>` per
219
+ app-side browser extension, and place them by the gate-placement paragraph that follows.
220
220
 
221
221
  Keep `conformance`, `tree`, `integration`, `distribution`, `studies`, and `service` as separate
222
222
  subjects.
@@ -230,6 +230,11 @@ parallelism in `service`. In a `private: true` workspace, never declare `prepubl
230
230
  `distribution`, reach `service` from `test`, and retain each isolated project's configuration.
231
231
  In both kinds of workspace, run `studies` on demand through `npm run test:studies` alone.
232
232
  Keep `test:studies` out of every gate and chain.
233
+ In a publishing workspace, run application and journey suites on demand through `test:app`,
234
+ `test:app:<environment>`, `test:app:<framework>`, `test:journey`, and
235
+ `test:journey:<framework>`. Keep them out of every release gate and chain.
236
+ In a `private: true` workspace, keep `test:app` in `test`, followed by `test:journey` and
237
+ each `test:journey:<framework>` the workspace declares.
233
238
 
234
239
  One project sits on neither axis. `probe` includes `tmp/probes/**/*.test.ts` so an agent can run a
235
240
  throwaway instrument against real sources, aliases and setup. Declare no proof there. Keep the