@orkestrel/scaffold 0.0.120 → 0.0.122

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 (78) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
  3. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
  4. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
  5. package/dist/bin/main.js +5 -5
  6. package/dist/bin/main.js.map +1 -1
  7. package/dist/host/agents/orchestration.md +16 -11
  8. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
  9. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
  10. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
  11. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
  12. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
  13. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
  14. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
  15. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
  16. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
  17. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  18. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
  19. package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
  20. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
  21. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
  22. package/dist/host/claude/AGENTS.md +1 -1
  23. package/dist/host/claude/agents/analyst.md +1 -1
  24. package/dist/host/claude/agents/opus.md +7 -6
  25. package/dist/host/claude/agents/orkestrel.md +26 -26
  26. package/dist/host/claude/agents/planner.md +3 -3
  27. package/dist/host/claude/agents/reviewer.md +3 -3
  28. package/dist/host/claude/agents/verifier.md +1 -1
  29. package/dist/host/claude/rules/campaign.md +3 -2
  30. package/dist/host/claude/rules/names.md +13 -7
  31. package/dist/host/claude/rules/tests.md +1 -1
  32. package/dist/host/claude/rules/workspace.md +9 -0
  33. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  34. package/dist/host/codex/agents/analyst.toml +2 -5
  35. package/dist/host/codex/agents/opus.toml +5 -3
  36. package/dist/host/codex/agents/planner.toml +6 -5
  37. package/dist/host/codex/agents/reviewer.toml +4 -7
  38. package/dist/host/codex/agents/verifier.toml +2 -2
  39. package/dist/host/dotfiles/gitignore +1 -2
  40. package/dist/host/guides/agent.md +5 -5
  41. package/dist/host/guides/brief.md +7 -15
  42. package/dist/host/guides/browser.md +1 -1
  43. package/dist/host/guides/capture.md +2 -2
  44. package/dist/host/guides/console.md +4 -30
  45. package/dist/host/guides/guide.md +0 -1
  46. package/dist/host/guides/interpret.md +165 -182
  47. package/dist/host/guides/lsp.md +26 -51
  48. package/dist/host/guides/mcp.md +220 -276
  49. package/dist/host/guides/middleware.md +14 -22
  50. package/dist/host/guides/ollama.md +1 -3
  51. package/dist/host/guides/probe.md +71 -80
  52. package/dist/host/guides/program.md +26 -35
  53. package/dist/host/guides/qualifier.md +0 -6
  54. package/dist/host/guides/queue.md +0 -4
  55. package/dist/host/guides/rater.md +6 -12
  56. package/dist/host/guides/relation.md +0 -2
  57. package/dist/host/guides/scaffold.md +18 -9
  58. package/dist/host/guides/sea.md +47 -51
  59. package/dist/host/guides/server.md +15 -19
  60. package/dist/host/guides/terminal.md +0 -26
  61. package/dist/host/guides/toolbox.md +0 -10
  62. package/dist/host/guides/worker.md +57 -57
  63. package/dist/host/guides/workflow.md +13 -26
  64. package/dist/host/guides/workspace.md +15 -21
  65. package/dist/host/manifest.json +63 -483
  66. package/dist/host/tests/config.test.ts +7 -0
  67. package/dist/src/core/index.cjs +13 -46
  68. package/dist/src/core/index.cjs.map +1 -1
  69. package/dist/src/core/index.js +13 -46
  70. package/dist/src/core/index.js.map +1 -1
  71. package/dist/src/server/index.cjs +10 -9
  72. package/dist/src/server/index.cjs.map +1 -1
  73. package/dist/src/server/index.d.cts +12 -8
  74. package/dist/src/server/index.d.ts +12 -8
  75. package/dist/src/server/index.js +10 -9
  76. package/dist/src/server/index.js.map +1 -1
  77. package/package.json +5 -5
  78. /package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +0 -0
@@ -8,9 +8,10 @@
8
8
  // edited. The second form reads every backticked token carrying a slash (a backslash counts and is
9
9
  // read as a slash), strips a `:line` or
10
10
  // `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
11
- // exist; a bare filename is outside the check. The two forms are two modes; name one. The script
12
- // refuses a flag it does not read, the `--flag=value` form included. Exit 3 when any is missing, 64
13
- // on usage.
11
+ // exist; a bare filename is outside the check. It also names each template section the brief omits:
12
+ // the `## Role and engine` section, and the `## Execution` section with its spawn-nothing sentence.
13
+ // The two forms are two modes; name one. The script refuses a flag it does not read, the
14
+ // `--flag=value` form included. Exit 3 when a path or a section is missing, 64 on usage.
14
15
  import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
15
16
  import { dirname, join, resolve } from 'node:path';
16
17
  import { fileURLToPath } from 'node:url';
@@ -23,6 +24,11 @@ export const LANES = Object.freeze({
23
24
  codex: 'tmp/codex',
24
25
  claude: 'tmp/claude',
25
26
  });
27
+ /** Lists the template sections every brief must keep, in template order. */
28
+ export const REQUIREMENTS = [
29
+ { heading: '## Role and engine', sentence: undefined },
30
+ { heading: '## Execution', sentence: 'Perform the assignment yourself and spawn nothing.' },
31
+ ];
26
32
  /** Lists the flags that take a value. */
27
33
  export const VALUE_FLAGS = ['--unit', '--lane', '--subject', '--check'];
28
34
  /** Lists every flag the script reads, value flags and switches alike. */
@@ -100,6 +106,42 @@ export function extractPaths(content) {
100
106
  .filter(readsAsPath));
101
107
  return [...found].sort();
102
108
  }
109
+ /**
110
+ * Reads the body of a level-two section.
111
+ *
112
+ * @param content - The brief text.
113
+ * @param heading - The heading line, such as `## Execution`.
114
+ * @returns The text between the heading line and the next level-two heading or the end, or
115
+ * undefined when no line equals the heading.
116
+ */
117
+ export function extractSection(content, heading) {
118
+ const lines = content.split(/\r\n|\n/u);
119
+ const start = lines.findIndex((line) => line.trimEnd() === heading);
120
+ if (start === -1)
121
+ return undefined;
122
+ const rest = lines.slice(start + 1);
123
+ const end = rest.findIndex((line) => line.startsWith('## '));
124
+ return (end === -1 ? rest : rest.slice(0, end)).join('\n');
125
+ }
126
+ /**
127
+ * Names each required template section a brief omits.
128
+ *
129
+ * @param content - The brief text.
130
+ * @param requirements - The sections the brief must keep.
131
+ * @returns One description per omission, in requirement order: the heading when its section is
132
+ * absent, and the sentence with its heading when the section is present without it.
133
+ */
134
+ export function scanOmissions(content, requirements) {
135
+ return requirements.flatMap(({ heading, sentence }) => {
136
+ const body = extractSection(content, heading);
137
+ const named = sentence === undefined ? '' : ` with the sentence ${JSON.stringify(sentence)}`;
138
+ if (body === undefined)
139
+ return [`the ${JSON.stringify(heading)} section${named}`];
140
+ if (sentence === undefined || body.replace(/\s+/gu, ' ').includes(sentence))
141
+ return [];
142
+ return [`the sentence ${JSON.stringify(sentence)} under ${JSON.stringify(heading)}`];
143
+ });
144
+ }
103
145
  /**
104
146
  * Resolves the first brief path for a unit that no file occupies.
105
147
  *
@@ -141,26 +183,32 @@ export function writeBrief(argv) {
141
183
  return 0;
142
184
  }
143
185
  /**
144
- * Checks that every path a brief names exists.
186
+ * Checks that every path a brief names exists and that the brief keeps every required section.
145
187
  *
146
188
  * @param path - The brief file.
147
- * @returns The exit code: 0 when every path exists, 3 when one is missing, 64 when the brief is not a file.
189
+ * @returns The exit code: 0 when every path exists and no section is omitted, 3 when a path is
190
+ * missing or a section is omitted, 64 when the brief is not a file.
148
191
  */
149
192
  export function checkBrief(path) {
150
193
  if (!existsSync(path) || !statSync(path).isFile()) {
151
194
  console.error(`brief: ${path} is not a file`);
152
195
  return 64;
153
196
  }
154
- const paths = extractPaths(readFileSync(path, 'utf8'));
197
+ const content = readFileSync(path, 'utf8');
198
+ const paths = extractPaths(content);
155
199
  const missing = paths.filter((candidate) => !existsSync(resolve(candidate)));
156
- console.log(JSON.stringify({ brief: path, checked: paths.length, missing }));
157
- return missing.length === 0 ? 0 : 3;
200
+ const omitted = scanOmissions(content, REQUIREMENTS);
201
+ console.log(JSON.stringify({ brief: path, checked: paths.length, missing, omitted }));
202
+ if (omitted.length > 0)
203
+ console.error(`brief: ${path} omits ${omitted.join('; ')}`);
204
+ return missing.length === 0 && omitted.length === 0 ? 0 : 3;
158
205
  }
159
206
  /**
160
207
  * Runs the script on its arguments.
161
208
  *
162
209
  * @param argv - The arguments after the script path.
163
- * @returns The exit code: 0 on success, 3 when a named path is missing, 64 on usage.
210
+ * @returns The exit code: 0 on success, 3 when a named path or a required section is missing, 64 on
211
+ * usage.
164
212
  */
165
213
  export function main(argv) {
166
214
  const unknown = readUnknownFlags(argv, FLAGS);
@@ -2,7 +2,8 @@
2
2
  // node .agents/skills/orkestrel-dispatch/scripts/chain.ts --plan FILE.json --journal DIR
3
3
  // The plan is a JSON array of steps, each `{ "name": "...", "command": "...", "args": ["..."] }`
4
4
  // with an optional `"cwd"` (a directory, relative to the working directory) and `"env"` (a record
5
- // of strings laid over this process's environment). A step name is letters, digits, dots,
5
+ // of strings laid over this process's environment by case-folded name, so an added variable drops
6
+ // every inherited one whose lower-cased name it claims). A step name is letters, digits, dots,
6
7
  // underscores, and hyphens, opens with a letter or digit, and is unique in the plan. Each step runs
7
8
  // with no shell and closed stdin, in plan order, with its standard output and standard error
8
9
  // written together to `DIR/<name>.txt`; the script prints one `name exit=N durationMs=N` line per
@@ -193,6 +194,25 @@ export function readStep(entry) {
193
194
  },
194
195
  ];
195
196
  }
197
+ /**
198
+ * Lays added variables over an inherited environment by case-folded name.
199
+ *
200
+ * @remarks
201
+ * A Windows environment block folds names by case, so an inherited `NPM_CONFIG_CACHE` would
202
+ * outrank an added `npm_config_cache`; every inherited variable whose lower-cased name an added
203
+ * variable claims is dropped first.
204
+ *
205
+ * @param inherited - The environment the child would inherit.
206
+ * @param added - The variables the step sets.
207
+ * @returns The inherited variables no added name claims, followed by the added variables.
208
+ */
209
+ export function mergeEnv(inherited, added) {
210
+ const claimed = new Set(Object.keys(added).map((name) => name.toLowerCase()));
211
+ return {
212
+ ...Object.fromEntries(Object.entries(inherited).filter(([name]) => !claimed.has(name.toLowerCase()))),
213
+ ...added,
214
+ };
215
+ }
196
216
  /**
197
217
  * Runs one step with no shell, its output and errors written together to a file.
198
218
  *
@@ -207,7 +227,7 @@ export function runStep(step, output) {
207
227
  try {
208
228
  const result = spawnSync(step.command, step.args, {
209
229
  cwd: step.cwd === undefined ? undefined : resolve(step.cwd),
210
- env: { ...process.env, ...step.env },
230
+ env: mergeEnv(process.env, step.env),
211
231
  stdio: ['ignore', descriptor, descriptor],
212
232
  windowsHide: true,
213
233
  shell: false,
@@ -1,6 +1,6 @@
1
- // Sweep source and tests for a prior version or range literal after a bump or a re-pin. Run from
2
- // the publishing package's root:
3
- // node .agents/skills/orkestrel-publish/scripts/pins.ts --version 0.0.76 [--range ^0.0.16 ...] [--paths src,tests] [--json]
1
+ // Sweep source, tests, and guides for a prior version or range literal after a bump or a re-pin.
2
+ // Run from the publishing package's root:
3
+ // node .agents/skills/orkestrel-publish/scripts/pins.ts --version 0.0.76 [--range ^0.0.16 ...] [--paths src,tests,guides] [--json]
4
4
  // `--range` repeats. A version hit is the literal bounded by characters other than digits and dots,
5
5
  // so `~0.0.76` and `"0.0.76"` both hit and `0.0.760` does not. A range that is one comparator over
6
6
  // one version (`^8.3.0`, `~8.3.0`, `>=8.3.0`, `v8.3.0`) hits its bare version in any form, bounded the
@@ -28,7 +28,7 @@ export const SKIPPED_DIRECTORIES = new Set([
28
28
  /** Lists every flag the script reads, value flags and switches alike. */
29
29
  export const FLAGS = ['--version', '--range', '--paths', '--json'];
30
30
  /** Holds the usage line the script prints on a usage refusal. */
31
- export const USAGE = 'usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]';
31
+ export const USAGE = 'usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests,guides] [--json]';
32
32
  /**
33
33
  * Normalizes a host path to forward slashes.
34
34
  *
@@ -208,7 +208,7 @@ export function main(argv) {
208
208
  }
209
209
  const version = readOptions(argv, '--version')[0];
210
210
  const ranges = readOptions(argv, '--range');
211
- const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests').split(',');
211
+ const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests,guides').split(',');
212
212
  if (version === undefined && ranges.length === 0) {
213
213
  console.error(USAGE);
214
214
  return 64;
@@ -1262,24 +1262,86 @@ export function runVerify(runner, scaffoldFile, scaffoldPrefix, offline, own) {
1262
1262
  .map((release) => `${release.name} ${release.range} vs ${String(release.latest)}`)
1263
1263
  .join(', '), drift.length === 0 ? 0 : 1);
1264
1264
  }
1265
+ /**
1266
+ * Reads the ranges the manifest declared in the commit that released a version.
1267
+ *
1268
+ * @remarks
1269
+ * The fleet's release commit carries the subject `Release <version>` and touches the manifest, and
1270
+ * the upload is exported from it, so its manifest holds the ranges the version shipped. A re-pin
1271
+ * made after it, committed or not, differs from those ranges, which `HEAD` alone cannot show.
1272
+ *
1273
+ * @param target - The target directory.
1274
+ * @param version - The released version.
1275
+ * @returns The ranges keyed by `field name` from the newest commit whose subject is exactly
1276
+ * `Release <version>`, or undefined when the target is no work tree, no such commit touched its
1277
+ * manifest, or that manifest is unreadable.
1278
+ */
1279
+ export function readReleasedRanges(target, version) {
1280
+ const subject = `Release ${version}`;
1281
+ const log = spawnSync('git', ['log', '--format=%H %s', '--fixed-strings', `--grep=${subject}`, '--', 'package.json'], { cwd: target, encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
1282
+ if (log.status !== 0)
1283
+ return undefined;
1284
+ const commit = log.stdout
1285
+ .split(/\r\n|\n/u)
1286
+ .map((line) => /^([0-9a-f]+) (.*)$/u.exec(line))
1287
+ .find((match) => match?.[2] === subject)?.[1];
1288
+ if (commit === undefined)
1289
+ return undefined;
1290
+ const shown = spawnSync('git', ['show', `${commit}:./package.json`], {
1291
+ cwd: target,
1292
+ encoding: 'utf8',
1293
+ windowsHide: true,
1294
+ maxBuffer: 64 * 1024 * 1024,
1295
+ });
1296
+ const manifest = shown.status === 0 ? parseJsonRecord(shown.stdout) : undefined;
1297
+ return manifest === undefined ? undefined : readRanges(manifest, RANGE_FIELDS);
1298
+ }
1299
+ /**
1300
+ * Collects every prior range that no longer stands in the final ranges.
1301
+ *
1302
+ * @param after - The ranges the manifest declares after the visit.
1303
+ * @param priors - Each earlier reading of the ranges, such as the release commit's and the visit's
1304
+ * starting ones.
1305
+ * @returns Each distinct range an earlier reading declared under a key whose final range differs,
1306
+ * in reading order.
1307
+ */
1308
+ export function collectPriorRanges(after, priors) {
1309
+ return [
1310
+ ...new Set(priors.flatMap((prior) => [...prior].filter(([key, range]) => after.get(key) !== range).map(([, range]) => range))),
1311
+ ];
1312
+ }
1265
1313
  /**
1266
1314
  * Runs the pins step.
1267
1315
  *
1316
+ * @remarks
1317
+ * The sweep takes every range that moved since the prior version's release commit as well as every
1318
+ * range the visit moved, so a re-pin made before the visit is swept too. Without that commit, or
1319
+ * under --dry-run, it takes the visit's moves alone; a run that executes the sweep names its source
1320
+ * in the row's note.
1321
+ *
1268
1322
  * @param runner - The visit's state.
1269
1323
  * @param before - The ranges the manifest declared before the visit.
1270
1324
  * @param version - The version to sweep for, or undefined when none is known.
1271
1325
  * @returns The number of hit lines, or undefined when the sweep did not run.
1272
1326
  */
1273
1327
  export function runPins(runner, before, version) {
1274
- const after = readRanges(readManifest(runner.target) ?? {}, RANGE_FIELDS);
1275
- const prior = [...before]
1276
- .filter(([name, range]) => after.get(name) !== range)
1277
- .flatMap(([, range]) => ['--range', range]);
1278
1328
  if (version === undefined) {
1279
1329
  appendStep(runner, 'pins', basename(PINS), 'no prior version to sweep for; pass --prior');
1280
1330
  return undefined;
1281
1331
  }
1282
- const swept = runStep(runner, 'pins', process.execPath, [PINS, '--version', version, ...prior], runner.target);
1332
+ const after = readRanges(readManifest(runner.target) ?? {}, RANGE_FIELDS);
1333
+ const released = runner.dry ? undefined : readReleasedRanges(runner.target, version);
1334
+ const prior = collectPriorRanges(after, released === undefined ? [before] : [released, before]);
1335
+ const source = released === undefined
1336
+ ? `no "Release ${version}" commit touched package.json; swept the ranges this visit moved`
1337
+ : `swept the ranges moved since the "Release ${version}" commit and by this visit`;
1338
+ const swept = runStep(runner, 'pins', process.execPath, [PINS, '--version', version, ...prior.flatMap((range) => ['--range', range])], runner.target, (result) => {
1339
+ const verdict = readVerdict(result);
1340
+ return {
1341
+ ...verdict,
1342
+ note: [verdict.note, source].filter((part) => part !== undefined).join('; '),
1343
+ };
1344
+ });
1283
1345
  return swept === undefined
1284
1346
  ? undefined
1285
1347
  : swept.stdout.split(/\r\n|\n/).filter((line) => /^\S+:\d+: /u.test(line)).length;
package/dist/bin/main.js CHANGED
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.120",
13
+ version: "0.0.122",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -102,7 +102,7 @@ var package_default = {
102
102
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
103
103
  },
104
104
  dependencies: {
105
- "@orkestrel/console": "^0.0.17",
105
+ "@orkestrel/console": "^0.0.18",
106
106
  "@orkestrel/contract": "^0.0.21",
107
107
  "@orkestrel/emitter": "^0.0.14",
108
108
  "@orkestrel/markdown": "^0.0.19",
@@ -111,10 +111,10 @@ var package_default = {
111
111
  },
112
112
  devDependencies: {
113
113
  "@microsoft/api-extractor": "^7.60.1",
114
- "@orkestrel/browser": "^0.0.30",
115
- "@orkestrel/guide": "^0.0.28",
114
+ "@orkestrel/browser": "^0.0.31",
115
+ "@orkestrel/guide": "^0.0.29",
116
116
  "@orkestrel/html": "^0.0.14",
117
- "@orkestrel/probe": "^0.0.26",
117
+ "@orkestrel/probe": "^0.0.27",
118
118
  "@orkestrel/test": "^0.0.32",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.0.5",