@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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +5 -5
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +16 -11
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/opus.md +7 -6
- package/dist/host/claude/agents/orkestrel.md +26 -26
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +3 -2
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/tests.md +1 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +2 -5
- package/dist/host/codex/agents/opus.toml +5 -3
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +4 -7
- package/dist/host/codex/agents/verifier.toml +2 -2
- package/dist/host/dotfiles/gitignore +1 -2
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/scaffold.md +18 -9
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +63 -483
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +13 -46
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +13 -46
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +10 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -8
- package/dist/src/server/index.d.ts +12 -8
- package/dist/src/server/index.js +10 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -5
- /package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +0 -0
|
@@ -45,6 +45,8 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
45
45
|
|
|
46
46
|
- Name the role and its engine in every dispatch. Reach a role by its own name. When a hosting harness offers both columns, the dispatch names the column each lane runs on.
|
|
47
47
|
- The capability column names the lane a role holds by default and the one a dispatch may assign (`reviewer`: subjective by default, objective when assigned; `orkestrel`: reader).
|
|
48
|
+
- A role holding the subjective lane judges whether the requested shape and voice are present, names and boundaries are coherent, the work sits at the right layer, each concept earns its place, and the guide matches the code. A role holding the objective lane judges correctness under adverse orderings, what the contracts and installed declarations permit, dependency and range truth, the missing seam or the assertion that cannot fail, and the letter of the rules. A charter points here for both lenses.
|
|
49
|
+
- `planner` also carries the read-only consultation § Engines admits for Claude Fable 5.1, on the engine the dispatch names.
|
|
48
50
|
- On a harness with no column, map each capability to an engine in the roster and route by that map; add the harness's column here when it carries campaign work.
|
|
49
51
|
- A driver launches another harness's CLI and returns the journal path and session id with the result. It never judges or implements. Refuse a bench result that carries no journal path and session id; it ran on the driver.
|
|
50
52
|
- `.agents/transports/<harness>.md` owns each bench's invocation, sandbox, journal, and recovery. `.claude/agents/` and `.codex/agents/` hold one file per role.
|
|
@@ -56,6 +58,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
56
58
|
- Keep small tedious precise tasks native: Claude Haiku in Claude, Codex Luna in Codex. Use `scout` for an exact bounded lookup; keep bench drivers, `checker`, and `verifier` on their mapped native engines. A bounded file scope does not turn context absorption or exploratory reading into a native lookup.
|
|
57
59
|
- Route a unit that authors path-containment, import-resolution-boundary, unescaped-input, or credential-exposure proofs to `opus` from the start where `opus` runs on Claude, and record the Codex bench dark for that unit only. Under native Codex roles, report a harness refusal through § Deviation protocol.
|
|
58
60
|
- Route gates to `verifier`. A writer's self-reported gate is not evidence. A writer never holds the runner lane for its own acceptance; a gate a writer runs is an observation, never acceptance.
|
|
61
|
+
- The Orchestrator runs a release visit and its installing chain, because they install and commit and `verifier` may not. `verifier` reruns the gates on the committed result when § Size gate names them.
|
|
59
62
|
- Record mechanical source adoption as Orchestrator integration or a writer unit. Reserve the runner name for a verifier that made no source repair.
|
|
60
63
|
- Under the Codex mapping, put falsify lanes on Astra or Sol at high effort; keep Luna for gates and verifier runs, never for a lane that must resolve runtime claims.
|
|
61
64
|
- Work directly on a one-file change or a one-line fix, subject to the preceding routing rules. Route standalone lookups through `scout`. Dispatch when isolation, parallelism, a second engine, or a large read pays for the brief.
|
|
@@ -160,6 +163,7 @@ A large change opens with a concise goal and its exit criterion, short enough to
|
|
|
160
163
|
- Permit a verifier to write its assigned evidence artifacts and the generated outputs its dispatch declares; never permit source repairs. A declaration names the command and each path the command writes or replaces. Declare a path only when the command regenerates it and no lane authors it, such as a build directory or a generated inventory file; an authored path is source, whichever command rewrites it. Declare no path for a command that only deletes. Keep each declared output outside every other lane's owned files and recorded fixtures, and hold it with the command's inputs for the run. Under this floor, the declared command can remove and rewrite its declared outputs, and that replacement is neither a destructive command nor a deletion.
|
|
161
164
|
- Record `git status --porcelain` before and after a declared command. Report each declared output that git tracks and the run changed; never revert it. When the run changed a path outside its declarations, stop and report the path.
|
|
162
165
|
- No role commits, pushes, tags, publishes, installs, or runs a destructive command.
|
|
166
|
+
- No lane, the Orchestrator included, runs `npm exec` or `npx` for a package the checkout does not install, because npm then fetches and runs the registry package of that name.
|
|
163
167
|
- No role, the Orchestrator included, runs `git checkout`, `git restore`, `git stash`, `git reset`, or `git clean`. Undo an edit by rewriting the text. Supply an untracked review input by its path; never stage it for review.
|
|
164
168
|
- No role, the Orchestrator included, reads, prints, copies, uploads, or packages a secret: `.env*`, `.npmrc`, `auth.json`, keys, tokens, `CURSOR_API_KEY`.
|
|
165
169
|
- A unit writes only under its owned files, its checkout's `tmp/`, and the declared outputs the preceding bullets permit. The Orchestrator's own briefs, probes, drafts, and records live in the checkout's `tmp/` too, never in a directory outside the repository; the user follows the work through the tree.
|
|
@@ -170,15 +174,16 @@ A large change opens with a concise goal and its exit criterion, short enough to
|
|
|
170
174
|
|
|
171
175
|
Every working file lives under the checkout's gitignored `tmp/`, in the directory its kind names.
|
|
172
176
|
|
|
173
|
-
| Directory | Holds
|
|
174
|
-
| ------------------------------------------ |
|
|
175
|
-
| `tmp/claude/`, `tmp/codex/`, `tmp/cursor/` | bench briefs, launch scripts, journals, `.err` files, last-message files, login logs, per harness
|
|
176
|
-
| `tmp/units/` | native unit briefs, reports, claims files, and unit records
|
|
177
|
-
| `tmp/probes/` | runtime probes the `probe` Vitest project collects and the `probe` MCP server arms, and a skill script's scratch under its own subdirectory (`census/`, `lint/`, `mutate/`)
|
|
178
|
-
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe`
|
|
179
|
-
| `tmp/captures/` | screenshots, resolved-style snapshots, and other capture portfolios
|
|
180
|
-
| `tmp/browsers/` | the journeys a `browse` server saves, their runs and captures, and its profiles under `.profiles/`
|
|
181
|
-
| `tmp/
|
|
177
|
+
| Directory | Holds |
|
|
178
|
+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
179
|
+
| `tmp/claude/`, `tmp/codex/`, `tmp/cursor/` | bench briefs, launch scripts, journals, `.err` files, last-message files, login logs, per harness |
|
|
180
|
+
| `tmp/units/` | native unit briefs, reports, claims files, and unit records |
|
|
181
|
+
| `tmp/probes/` | runtime probes the `probe` Vitest project collects and the `probe` MCP server arms, and a skill script's scratch under its own subdirectory (`census/`, `lint/`, `mutate/`) |
|
|
182
|
+
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe` |
|
|
183
|
+
| `tmp/captures/` | screenshots, Vitest's `page.screenshot()` captures under `screenshots/` included, resolved-style snapshots, and other capture portfolios |
|
|
184
|
+
| `tmp/browsers/` | the journeys a `browse` server saves, their runs and captures, and its profiles under `.profiles/` |
|
|
185
|
+
| `tmp/studies/` | the results, closures, gradings, labels, scratch, and run records the `@orkestrel/study` executable writes under `tmp/studies/<id>`, its default output, and the study data a consumer keeps out of its tracked tree; outside the directories `sweep.ts --tmp` deletes from |
|
|
186
|
+
| `tmp/worktrees/` | worktrees the Orchestrator creates for a parallel writer |
|
|
182
187
|
|
|
183
188
|
## .orkestrel layout
|
|
184
189
|
|
|
@@ -206,7 +211,7 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
|
|
|
206
211
|
## Benches
|
|
207
212
|
|
|
208
213
|
- Probe a bench with the dispatch skill's `scripts/bench.ts` and the model its transport pins before its first lane in a session. A version string or a login status is not liveness.
|
|
209
|
-
- For a harness that uses a bench, record a dispatch that fails on auth, quota, model access, or network as bench dark and re-plan the lane: Astra bench dark →
|
|
214
|
+
- For a harness that uses a bench, record a dispatch that fails on auth, quota, model access, or network as bench dark and re-plan the lane: Astra bench dark → `opus` takes `astra`'s units, and `planner` takes `analyst`'s design arguments and `reviewer` its audits, each holding the objective lane on Claude Opus; when the unit under review was written on Claude Opus, dispatch `reviewer` with `model: sonnet`; Claude Opus bench dark → Astra holds the subjective lane too; Grok dark → the harness's native reader, `distiller` or `researcher`: Claude Haiku 5.5 in Claude Code, GPT-6 Luna under the Codex mapping. When Haiku refuses the read, re-dispatch the role with `model: sonnet`. Record every substitution in the brief and in the commit that carries the unit. For a native role failure, use § Deviation protocol without a Claude fallback prerequisite.
|
|
210
215
|
- Never assign Grok a design or review lane in Claude Code or Codex.
|
|
211
216
|
- Journal every bench run under `tmp/<bench>/` with its session id. Never commit a journal.
|
|
212
217
|
|
|
@@ -234,5 +239,5 @@ The Orchestrator triages: obvious correction → tighten and re-dispatch; missin
|
|
|
234
239
|
- Before calling work ready, try the shipped result as the user will, on the build they run, and report what did not run.
|
|
235
240
|
- Substitute an engine only when the same session recorded the bench dark; name the fallback in the brief and the carrying commit.
|
|
236
241
|
- In a repository whose package the registry already serves, commit on the main branch and push it only on the user's go-ahead.
|
|
237
|
-
- Commit by explicit paths. Before a push, read `git log @{upstream}..` and push only commits meant to publish together; hold a push while a commit
|
|
242
|
+
- Commit by explicit paths. Before a push, read `git log @{upstream}..` and push only commits meant to publish together; hold a push while a commit imports a name that no registry-served version within its committed ranges carries, a name only an unpublished local pin carries included. Push a commit only after the gate run on that commit, or record the push as ungated.
|
|
238
243
|
- Publishing is the user's decision and credential; `orkestrel-publish` owns the release procedure, the bump rules, and the dependency-tarball rules.
|
|
@@ -13,25 +13,25 @@ description: >-
|
|
|
13
13
|
| Script | Does |
|
|
14
14
|
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
15
|
| `scripts/bench.ts` | `--cursor [--resolve]`, `--codex [--sandbox MODE]`, or `--claude`, each with `[--model ID] [--cap SECONDS]`: resolves the bench entry, reads its version and login, runs one bounded round trip into `tmp/<bench>/bench.jsonl`, and prints JSON with `live`; `--resolve` prints the Cursor entry alone. A malformed cap, a `--sandbox` outside `read-only`, `workspace-write`, and `danger-full-access`, or `--resolve` without `--cursor` is a usage fault, never a dark bench. Exit 3 when the bench is dark, 64 on usage. |
|
|
16
|
-
| `scripts/brief.ts` | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root. Exit 3 when
|
|
16
|
+
| `scripts/brief.ts` | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root, and names the `## Role and engine` section or the `## Execution` section's spawn-nothing sentence when the brief omits it. Exit 3 when a path or a section is missing. |
|
|
17
17
|
| `scripts/launch.ts` | `--journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]` runs the command with no shell and closed stdin, kills it at the cap (its process tree on Windows), records `git status --porcelain` before and after with `--status`, prints a spawn line carrying the `pid` when the command starts, writes that pid to `<journal>.pid`, and ends the errors file with `exit=`. Exit 124 when capped; 127 when the command cannot start (the errors file names why); 64 on usage, including a cap above 2147483 seconds. |
|
|
18
18
|
| `scripts/login.ts` | `--codex [--cap SECONDS]` reads `codex login status`, runs `codex login --device-auth` journaled to `tmp/codex/login.log` when it is not logged in, prints the URL and the one-time code as they appear, and polls the status until it answers or the cap ends, ending any status read that outlasts the cap, and refuses a cap above 2147483 seconds; `--claude` reads `claude auth status`. Exit 0 logged in, 3 not. |
|
|
19
19
|
| `scripts/result.ts` | `--cursor\|--claude\|--codex JOURNAL [--out PATH]` prints the session id, the answer length, the run's `exit`, `capped`, and `durationMs` from the errors file, and the journal's `bytes`, `ageMs`, and `lastEvent`. Exit 3 when the journal carries no session or answer. |
|
|
20
20
|
| `scripts/cite.ts` | `PATH [--root DIR] [--json]` lists every `file:line` citation in a report whose file does not exist or whose line is past the end. Exit 3 when one does not resolve. |
|
|
21
21
|
| `scripts/sweep.ts` | `--report` lists leftovers under `tmp/` and `.orkestrel/` by age, deletes nothing, and flags a `.orkestrel/**/*.md` line that cites a backticked path git ignores or names a machine path; `--tmp [--older-than MINUTES]` deletes stale launch files and refuses while a journal is changing; `--unit UNIT [--delete]` lists or deletes one accepted unit's brief, report, claims, journal, errors, status, pid, and last-message files; `--tmp` and `--unit --delete` keep every file git tracks and print `kept tracked <path>`. |
|
|
22
|
-
| `scripts/chain.ts` | `--plan FILE.json --journal DIR` runs the steps of a JSON plan (`name`, `command`, `args`, optional `cwd` and `env`) in order with no shell, writes each step's output to `<journal>/<name>.txt`, prints one `name exit= durationMs=` line per step, and stops at the first step that does not exit 0. Exit is that step's code; 2 when a step cannot start; 64 on usage.
|
|
22
|
+
| `scripts/chain.ts` | `--plan FILE.json --journal DIR` runs the steps of a JSON plan (`name`, `command`, `args`, optional `cwd` and `env`, an `env` name dropping every inherited variable whose lower-cased name it claims) in order with no shell, writes each step's output to `<journal>/<name>.txt`, prints one `name exit= durationMs=` line per step, and stops at the first step that does not exit 0. Exit is that step's code; 2 when a step cannot start; 64 on usage. |
|
|
23
23
|
| `scripts/patch.ts` | `EDITS.md (--plan \| --apply) [--skip N ...]` applies an edit file of `### <path>` blocks, each with a `reason:` line and fenced `old:` and `new:` texts: every `old` text must occur exactly once in its file after the earlier edits to that file (however the blocks spell its path), and nothing is written unless every selected edit resolves. `--plan` prints each edit's resolution; `--skip N` leaves out edit N and repeats. Exit 1 when an edit does not resolve, 64 on usage. |
|
|
24
24
|
|
|
25
25
|
## Write the brief
|
|
26
26
|
|
|
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. Cite each law by file and section; quote a law the brief carries, never paraphrase it. A re-run takes the `-<n>` file the script writes; never edit a launched brief.
|
|
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.
|
|
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. Class a failure that passes when rerun alone by its cause: contention from a peer session is a host limit; contention from the session's own concurrent lanes breaks `.agents/skills/orkestrel-parallel/SKILL.md` § Bound the host, and the step reruns alone within that bound; any other failure that passes alone is an order-dependent defect to diagnose, never a timing miss to record. An unchanged rerun of the sequence that produced the failure 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
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.
|
|
34
|
-
8. Run `brief.ts --check <brief>` and fix every missing path before the launch.
|
|
34
|
+
8. Run `brief.ts --check <brief>` and fix every missing path and omitted section before the launch.
|
|
35
35
|
|
|
36
36
|
When a unit may attribute a failed command to its baseline, require its pre-edit output, exit code,
|
|
37
37
|
and input identity before writing; otherwise report the attribution as unverified.
|
|
@@ -6,6 +6,7 @@ Apply these rules to every command that outlives the turn that starts it: a benc
|
|
|
6
6
|
|
|
7
7
|
- Launch as a harness-tracked background command through `scripts/launch.ts` under a hard cap, per § Launch ownership.
|
|
8
8
|
- Spawn a package manager through its JavaScript entry; `.agents/platforms/<platform>.md` names the entry and the shell quirks of each host.
|
|
9
|
+
- When a chain's scripts must run on a selected Node, launch the chain under a `PATH` that leads with that Node's directory: npm resolves a script's `node` from `PATH` and adds no directory of the Node running it.
|
|
9
10
|
- Write a multi-step chain as a TypeScript file run by `node`, with an opening comment naming its log and its cap. Never edit a script while it runs: copy, edit the copy, launch the copy.
|
|
10
11
|
- Run the first use of any flag, subcommand, or quoting form in a throwaway probe, never inside a unit.
|
|
11
12
|
- Keep network-dependent work (installs, lockfile generation, live fetches) out of sandboxed bench execs.
|
|
@@ -29,7 +30,7 @@ Apply these rules to every command that outlives the turn that starts it: a benc
|
|
|
29
30
|
- Read liveness, list descendants, and kill with the commands of `.agents/platforms/<platform>.md`: list every descendant of the recorded pid, print the list, then kill each listed id and the recorded pid.
|
|
30
31
|
- Refuse a list holding PID 1, the harness shell, or an id outside the descent of the recorded pid. At the cap, `launch.ts` kills what the platform page states; kill the remaining listed descendants by hand.
|
|
31
32
|
- Confirm the recorded process and every listed descendant are gone before another writer takes the files. Check owned-file mtimes before dispatching the substitute.
|
|
32
|
-
- Rerun a failure alone only after the unit exits,
|
|
33
|
+
- Rerun a failure alone only after the unit exits, and class the reading per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief; a unit's own rerun is never alone.
|
|
33
34
|
|
|
34
35
|
## Cap
|
|
35
36
|
|
|
@@ -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.
|
|
12
|
-
//
|
|
13
|
-
//
|
|
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'
|
|
@@ -33,6 +34,18 @@ export const LANES: Readonly<Record<string, string>> = Object.freeze({
|
|
|
33
34
|
claude: 'tmp/claude',
|
|
34
35
|
})
|
|
35
36
|
|
|
37
|
+
/** Describes a template section a brief must keep: its heading and the sentence it must carry. */
|
|
38
|
+
export interface Requirement {
|
|
39
|
+
readonly heading: string
|
|
40
|
+
readonly sentence: string | undefined
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Lists the template sections every brief must keep, in template order. */
|
|
44
|
+
export const REQUIREMENTS: readonly Requirement[] = [
|
|
45
|
+
{ heading: '## Role and engine', sentence: undefined },
|
|
46
|
+
{ heading: '## Execution', sentence: 'Perform the assignment yourself and spawn nothing.' },
|
|
47
|
+
]
|
|
48
|
+
|
|
36
49
|
/** Lists the flags that take a value. */
|
|
37
50
|
export const VALUE_FLAGS: readonly string[] = ['--unit', '--lane', '--subject', '--check']
|
|
38
51
|
|
|
@@ -125,6 +138,44 @@ export function extractPaths(content: string): readonly string[] {
|
|
|
125
138
|
return [...found].sort()
|
|
126
139
|
}
|
|
127
140
|
|
|
141
|
+
/**
|
|
142
|
+
* Reads the body of a level-two section.
|
|
143
|
+
*
|
|
144
|
+
* @param content - The brief text.
|
|
145
|
+
* @param heading - The heading line, such as `## Execution`.
|
|
146
|
+
* @returns The text between the heading line and the next level-two heading or the end, or
|
|
147
|
+
* undefined when no line equals the heading.
|
|
148
|
+
*/
|
|
149
|
+
export function extractSection(content: string, heading: string): string | undefined {
|
|
150
|
+
const lines = content.split(/\r\n|\n/u)
|
|
151
|
+
const start = lines.findIndex((line) => line.trimEnd() === heading)
|
|
152
|
+
if (start === -1) return undefined
|
|
153
|
+
const rest = lines.slice(start + 1)
|
|
154
|
+
const end = rest.findIndex((line) => line.startsWith('## '))
|
|
155
|
+
return (end === -1 ? rest : rest.slice(0, end)).join('\n')
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Names each required template section a brief omits.
|
|
160
|
+
*
|
|
161
|
+
* @param content - The brief text.
|
|
162
|
+
* @param requirements - The sections the brief must keep.
|
|
163
|
+
* @returns One description per omission, in requirement order: the heading when its section is
|
|
164
|
+
* absent, and the sentence with its heading when the section is present without it.
|
|
165
|
+
*/
|
|
166
|
+
export function scanOmissions(
|
|
167
|
+
content: string,
|
|
168
|
+
requirements: readonly Requirement[],
|
|
169
|
+
): readonly string[] {
|
|
170
|
+
return requirements.flatMap(({ heading, sentence }) => {
|
|
171
|
+
const body = extractSection(content, heading)
|
|
172
|
+
const named = sentence === undefined ? '' : ` with the sentence ${JSON.stringify(sentence)}`
|
|
173
|
+
if (body === undefined) return [`the ${JSON.stringify(heading)} section${named}`]
|
|
174
|
+
if (sentence === undefined || body.replace(/\s+/gu, ' ').includes(sentence)) return []
|
|
175
|
+
return [`the sentence ${JSON.stringify(sentence)} under ${JSON.stringify(heading)}`]
|
|
176
|
+
})
|
|
177
|
+
}
|
|
178
|
+
|
|
128
179
|
/**
|
|
129
180
|
* Resolves the first brief path for a unit that no file occupies.
|
|
130
181
|
*
|
|
@@ -168,27 +219,32 @@ export function writeBrief(argv: readonly string[]): number {
|
|
|
168
219
|
}
|
|
169
220
|
|
|
170
221
|
/**
|
|
171
|
-
* Checks that every path a brief names exists.
|
|
222
|
+
* Checks that every path a brief names exists and that the brief keeps every required section.
|
|
172
223
|
*
|
|
173
224
|
* @param path - The brief file.
|
|
174
|
-
* @returns The exit code: 0 when every path exists
|
|
225
|
+
* @returns The exit code: 0 when every path exists and no section is omitted, 3 when a path is
|
|
226
|
+
* missing or a section is omitted, 64 when the brief is not a file.
|
|
175
227
|
*/
|
|
176
228
|
export function checkBrief(path: string): number {
|
|
177
229
|
if (!existsSync(path) || !statSync(path).isFile()) {
|
|
178
230
|
console.error(`brief: ${path} is not a file`)
|
|
179
231
|
return 64
|
|
180
232
|
}
|
|
181
|
-
const
|
|
233
|
+
const content = readFileSync(path, 'utf8')
|
|
234
|
+
const paths = extractPaths(content)
|
|
182
235
|
const missing = paths.filter((candidate) => !existsSync(resolve(candidate)))
|
|
183
|
-
|
|
184
|
-
|
|
236
|
+
const omitted = scanOmissions(content, REQUIREMENTS)
|
|
237
|
+
console.log(JSON.stringify({ brief: path, checked: paths.length, missing, omitted }))
|
|
238
|
+
if (omitted.length > 0) console.error(`brief: ${path} omits ${omitted.join('; ')}`)
|
|
239
|
+
return missing.length === 0 && omitted.length === 0 ? 0 : 3
|
|
185
240
|
}
|
|
186
241
|
|
|
187
242
|
/**
|
|
188
243
|
* Runs the script on its arguments.
|
|
189
244
|
*
|
|
190
245
|
* @param argv - The arguments after the script path.
|
|
191
|
-
* @returns The exit code: 0 on success, 3 when a named path is missing, 64 on
|
|
246
|
+
* @returns The exit code: 0 on success, 3 when a named path or a required section is missing, 64 on
|
|
247
|
+
* usage.
|
|
192
248
|
*/
|
|
193
249
|
export function main(argv: readonly string[]): number {
|
|
194
250
|
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
|
|
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
|
|
@@ -235,6 +236,31 @@ export function readStep(entry: unknown): readonly Step[] {
|
|
|
235
236
|
]
|
|
236
237
|
}
|
|
237
238
|
|
|
239
|
+
/**
|
|
240
|
+
* Lays added variables over an inherited environment by case-folded name.
|
|
241
|
+
*
|
|
242
|
+
* @remarks
|
|
243
|
+
* A Windows environment block folds names by case, so an inherited `NPM_CONFIG_CACHE` would
|
|
244
|
+
* outrank an added `npm_config_cache`; every inherited variable whose lower-cased name an added
|
|
245
|
+
* variable claims is dropped first.
|
|
246
|
+
*
|
|
247
|
+
* @param inherited - The environment the child would inherit.
|
|
248
|
+
* @param added - The variables the step sets.
|
|
249
|
+
* @returns The inherited variables no added name claims, followed by the added variables.
|
|
250
|
+
*/
|
|
251
|
+
export function mergeEnv(
|
|
252
|
+
inherited: Readonly<Record<string, string | undefined>>,
|
|
253
|
+
added: Readonly<Record<string, string>>,
|
|
254
|
+
): Record<string, string | undefined> {
|
|
255
|
+
const claimed = new Set(Object.keys(added).map((name) => name.toLowerCase()))
|
|
256
|
+
return {
|
|
257
|
+
...Object.fromEntries(
|
|
258
|
+
Object.entries(inherited).filter(([name]) => !claimed.has(name.toLowerCase())),
|
|
259
|
+
),
|
|
260
|
+
...added,
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
|
|
238
264
|
/**
|
|
239
265
|
* Runs one step with no shell, its output and errors written together to a file.
|
|
240
266
|
*
|
|
@@ -249,7 +275,7 @@ export function runStep(step: Step, output: string): Finish {
|
|
|
249
275
|
try {
|
|
250
276
|
const result = spawnSync(step.command, step.args, {
|
|
251
277
|
cwd: step.cwd === undefined ? undefined : resolve(step.cwd),
|
|
252
|
-
env:
|
|
278
|
+
env: mergeEnv(process.env, step.env),
|
|
253
279
|
stdio: ['ignore', descriptor, descriptor],
|
|
254
280
|
windowsHide: true,
|
|
255
281
|
shell: false,
|
|
@@ -18,7 +18,8 @@ Give every claims brief these rows.
|
|
|
18
18
|
|
|
19
19
|
- Give a lane every row of § Rows plus **Role and lane** (the role, its engine, which lane it holds) and **Output** (the verdict shape and its single terminal line from `SKILL.md` § Verdict shape).
|
|
20
20
|
- Omit the writer rows: owned, shared, and off-limits files; acceptance criteria stated as gate commands. Keep the sentence that the lane performs the assignment itself and spawns nothing.
|
|
21
|
-
-
|
|
21
|
+
- Supply each receipt a claim needs (the command, its input identity, and its exit), and never ask a read-only lane to run a command or hand it a gate criterion.
|
|
22
|
+
- Keep the verdict shape `SKILL.md` § Verdict shape fixes; replace it only when a skill the dispatch names fixes another.
|
|
22
23
|
|
|
23
24
|
## The successor brief
|
|
24
25
|
|
|
@@ -7,7 +7,7 @@ description: Research, audit, refactor, implement, centralize, test, document, a
|
|
|
7
7
|
|
|
8
8
|
## Read
|
|
9
9
|
|
|
10
|
-
`AGENTS.md` § Authority and loading names the files every unit reads. This skill adds the references the selected
|
|
10
|
+
`AGENTS.md` § Authority and loading names the files every unit reads. This skill adds the references the selected phases name, the contracts, barrels, manifest, and configuration those phases need, and every decision-bearing implementation file the user names, read first-hand by the decision owner. Delegate bulk reconnaissance and supporting research, never the design decision. Preserve dirty and user-owned work.
|
|
11
11
|
|
|
12
12
|
## Scripts
|
|
13
13
|
|
|
@@ -17,13 +17,13 @@ Run each from the checkout root. Each script's opening comment owns its behavior
|
|
|
17
17
|
- `scripts/titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]` compares the `describe`, `it`, `test`, and `suite` titles of `tests/**/*.test.ts` against `REV`. It flags a title registered fewer times than at `REV` as missing, or as moved when another string literal in `tests/**/*.ts` spells it; the reader rules each moved row by reading its holder. It reports each registration whose title is no literal (dynamic), which the comparison cannot follow, and flags a file that registers fewer of them than at `REV` (lost dynamic). It cannot see a removed `.each` table row or a title registered through an alias such as a `test.extend` result. `--root` defaults to the working directory and may sit below the repository top; `REV` may not open with `-`. Exit 0 no missing or moved title and no lost-dynamic file, 3 any of them, 2 git, filesystem, or lexical refusal, 64 usage.
|
|
18
18
|
- `scripts/measure.ts --rule ID [--options JSON] PATH...` counts one lint rule's hits over the named paths before the rule is enabled. It writes a variant config under `tmp/probes/lint/` that enables only that rule as an error beside the workspace's `plugins` and `jsPlugins` (so a `policy/` rule loads), runs the installed oxlint from the checkout root, and prints the total and the hits per file. A hit is a diagnostic whose code names the rule; another diagnostic, a parse error included, or a linter status other than a clean 0 or 1 refuses the count. `--options` is the rule's JSON options, an array spread after `error` or one value. The variant carries no `ignorePatterns` and no override, so it reads exactly the named paths. It needs `npm ci` first. Exit 0 no hit, 3 a hit, 2 the config or the linter cannot run or reports another diagnostic, 64 usage.
|
|
19
19
|
|
|
20
|
-
## Select the
|
|
20
|
+
## Select the phases
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Run the smallest selection of phases that fully satisfies the request:
|
|
23
23
|
|
|
24
24
|
- **Structural:** centralization, nested-function removal, wrapper cleanup, or test-infrastructure consolidation.
|
|
25
25
|
- **Capability:** research and implement named missing behavior or upstream parity.
|
|
26
|
-
- **Hardening:**
|
|
26
|
+
- **Hardening:** every phase of the complete production-readiness workflow.
|
|
27
27
|
- **Documentation:** a guide, README, or TSDoc pass on one package; it runs step 10 alone.
|
|
28
28
|
|
|
29
29
|
A narrow structural request does not authorize unrelated API redesign. A hardening request does authorize fixing every verified in-scope defect and completing every in-scope deferred capability.
|
|
@@ -32,15 +32,15 @@ Load [research.md](references/research.md) for upstream comparisons, legacy/`old
|
|
|
32
32
|
|
|
33
33
|
Load [contract.md](references/contract.md) whenever the package declares `@orkestrel/contract`, the user requests contract adoption, or local code overlaps validation, parsing, outcomes, safe exception capture, schemas, or contract generation.
|
|
34
34
|
|
|
35
|
-
Load [centralization.md](references/centralization.md) for every structural
|
|
35
|
+
Load [centralization.md](references/centralization.md) for every structural selection and as a mandatory cleanup pass after capability or hardening work.
|
|
36
36
|
|
|
37
|
-
Load [hardening.md](references/hardening.md) for
|
|
37
|
+
Load [hardening.md](references/hardening.md) for a hardening selection, for any request involving concurrency, lifecycle pressure, security boundaries, real services/models, test discovery, or package inspection, and before any repair round at a seam.
|
|
38
38
|
|
|
39
|
-
Load [document.md](references/document.md) for
|
|
39
|
+
Load [document.md](references/document.md) for a documentation selection and for step 10 of every other selection.
|
|
40
40
|
|
|
41
41
|
Load [bindings.md](references/bindings.md) for a census or a sweep under `.claude/rules/typescript.md` § Bindings, together with [equivalence.md](references/equivalence.md). Before a census item becomes a lint rule, count the rule's hits with `scripts/measure.ts`.
|
|
42
42
|
|
|
43
|
-
Load [equivalence.md](references/equivalence.md) for a structural
|
|
43
|
+
Load [equivalence.md](references/equivalence.md) for a structural selection whose rewrite claims unchanged behavior, and cite it in the claims of the review that judges one.
|
|
44
44
|
|
|
45
45
|
## Execute the workflow
|
|
46
46
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Production hardening
|
|
2
2
|
|
|
3
|
-
This reference governs
|
|
3
|
+
This reference governs a hardening selection: the package's bounds, the risk and seam matrix, real-implementation testing, live-service tests, lifecycle pressure, holding the bounds, security paths, the test audit, and generated outputs.
|
|
4
4
|
|
|
5
5
|
## Build the risk and seam matrix
|
|
6
6
|
|
|
@@ -80,7 +80,7 @@ A seam's finding concerns the package when it falsifies a promise the contract m
|
|
|
80
80
|
- When a finding falsifies a promise, repair it within its row and close the repair with the mutation probe `.agents/orchestration.md` § Size gate names.
|
|
81
81
|
- When a finding describes a host behavior the contract never promised to survive, open one design question on the package's dependence on that behavior: remove the dependence, narrow the promise, or refuse on that host. Never add a mechanism around the behavior.
|
|
82
82
|
- When a finding is outside the bounds and below the release bar, record it in the deferral list (`.claude/rules/campaign.md` § Content), and reopen it only when its trigger fires.
|
|
83
|
-
- Before another round at one seam, weigh a further repair against a design question and re-examine the stop set for that seam against the signals `.agents/orchestration.md` § Size gate names;
|
|
83
|
+
- Before another round at one seam, weigh a further repair against a design question and re-examine the stop set for that seam against the signals `.agents/orchestration.md` § Size gate names; a hardening selection adds one: findings move from the contract to the host.
|
|
84
84
|
- A seam that reprices on every edit (a count, a timing) is not a seam; drop the claim per the `orkestrel-falsify` skill § End the depth search.
|
|
85
85
|
|
|
86
86
|
## Audit security and destructive paths
|
|
@@ -96,7 +96,7 @@ For every fetch, write, delete, extraction, path, protocol, or authentication bo
|
|
|
96
96
|
|
|
97
97
|
## Audit the tests themselves
|
|
98
98
|
|
|
99
|
-
Run the discovery census, `scripts/discovery.ts` as `SKILL.md` § Scripts states (step 11 of the
|
|
99
|
+
Run the discovery census, `scripts/discovery.ts` as `SKILL.md` § Scripts states (step 11 of the workflow): which project collects each file, which gate reaches each project, and where a file carries `.todo`, a conditional skip (`.skipIf`, `.runIf`), `.fails`, a retry, or a timeout. `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse `.only` and `.skip`. Then verify:
|
|
100
100
|
|
|
101
101
|
- every intended test file is collected by the correct project, and the test counts and environments match the intent;
|
|
102
102
|
- judge each discovered project's invocation and gate membership by `.claude/rules/workspace.md` § Test project matrix; read each reported chain and rule each workbench by its purpose;
|
|
@@ -13,7 +13,7 @@ description: >-
|
|
|
13
13
|
| Within one session | subagents, child tasks, and background commands the session launches | launch results and completion notices |
|
|
14
14
|
| Across sessions | separate top-level sessions on one machine sharing a checkout, the host, or the execution lane | messages that wake the receiving session; one tracked coordination record when no such channel reaches it |
|
|
15
15
|
|
|
16
|
-
- Read the page for each harness that hosts a lane before its first launch: `references/claude.md`, `references/codex.md`, `references/cursor.md`, `references/t3.md`, or `references/cloud.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
|
|
16
|
+
- Read the page for each harness that hosts a lane before its first launch: `references/claude-code.md`, `references/codex.md`, `references/cursor.md`, `references/t3.md`, or `references/cloud.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
|
|
17
17
|
- Apply `.agents/orchestration.md` for routing, session reuse, consultation, independence, and acceptance.
|
|
18
18
|
|
|
19
19
|
## Scripts
|
|
@@ -119,7 +119,7 @@ Apply this section when two sessions on one machine share the tests, checks, bui
|
|
|
119
119
|
- One session runs process-running commands at a time. Ask the holder for the lane in one message; the holder hands it over in one message as soon as its running command exits. Silence is no handover.
|
|
120
120
|
- While another session holds the lane, edit your own files, read, and queue your commands.
|
|
121
121
|
- Hand the lane over by naming the last command's exit and that none of your processes still runs. Set no clock windows and send no per-command acknowledgments.
|
|
122
|
-
-
|
|
122
|
+
- Class contention from another session per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief. Rerun the interrupted unit alone after the window clears.
|
|
123
123
|
- When the user stops work, send the stop to every affected session. Withdraw queued work by its id and preserve finished evidence.
|
|
124
124
|
- When no message channel reaches a peer session, coordinate through one tracked record holding owned paths and a dated log. Read its latest entry before each unit, log each landing, and delete the record when the shared work closes.
|
|
125
125
|
- A session that finds another session's hand-off record without the user's go-ahead reads it for context only.
|
|
@@ -21,13 +21,13 @@ description: Run an Orkestrel release from layer order to registry confirmation,
|
|
|
21
21
|
|
|
22
22
|
## Scripts
|
|
23
23
|
|
|
24
|
-
| Script | Does
|
|
25
|
-
| -------------------- |
|
|
26
|
-
| `scripts/compare.ts` | `[--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]`, run from the package root after its build: fetches the published tarball and lists the material differences from the rebuilt `dist/` (sourcemaps excluded, whitespace-only differences ignored). Exit 0 when nothing differs, 3 when something does, 2 when the tarball cannot be read, 64 on usage (no package name, no `dist/`, or `--tarball` with no path).
|
|
27
|
-
| `scripts/pins.ts` | `--version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]`, run from the package root: lists every line under the paths carrying the prior version literal or a prior range literal, once per line, sweeping a one-comparator range such as `^8.3.0` for its bare version in any form. Exit 0 with no hits, 3 with hits, 64 on usage (no literal, or a flag with no value).
|
|
28
|
-
| `scripts/swap.ts` | One mode per run, from any directory: `--pin --consumer DIR --source DIR [--source DIR ...] [--override NAME ...] [--no-build] [--dry-run] [--json]` refuses a source whose packed manifest names a local dependency spec in any dependency field (a `file:` or `link:` prefix, a path start of `.`, `~/`, `/`, `\`, or a drive letter, or a protocol-free archive name ending in `.tgz`, `.tar.gz`, or `.tar` that is not a `user/repo` shorthand), builds and packs each source into `<consumer>/tmp/tarballs/` under a name carrying its SHA-256, records each replaced range in the ledger `pins.json` there, the record of which build the consumer runs, writes each tarball's absolute `file:` spec and each `--override` (repeatable, like `--source`) where oxfmt sorts it, installs, and proves that every pinned source, an override-only one included, is installed with the source's bytes; `--restore --consumer DIR [--package NAME ...] [--json]` puts back each recorded range and override, keeps an `overrides` block that existed before the pin, installs, proves the restored copy, and lists the re-pin arguments, and refuses with 64, before it writes anything, a ledger whose package or override keys are not package names or whose removal would leave `node_modules`; `--status --consumer DIR [--json]` writes nothing and reports drift between the ledger, the manifest, the tarballs, the installed bytes, and the source commits, a manifest spec holding its tarball only when it names the ledger archive's location. `--pin` and `--restore` write a receipt under `tmp/units/`. Exit 0 on success, 1 when a command or a proof failed, 3 when `--status` reports drift, 64 on usage.
|
|
29
|
-
| `scripts/wave.ts` | `--visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE]` runs one repository's visit in the order [wave.md](references/wave.md) § Visit a repository fixes (pin, commit, overwrite, verify, install, pins, format, record, gates, compare), stops at the first failing step, journals each executed step's full output under the target's `tmp/units/wave/` when the work tree ignores `tmp/` and names the journal in its row, and prints each step's exit (a failed step names the `code: message` refusal or the `note` a JSON verb writes on stdout, else the last stderr lines), the bump ruling (the rebuilt dist against the published tarball, and the final runtime dependency set against the published manifest), and a row for `.orkestrel/release.md`; `--prior` names the version a pre-ruled bump replaced so the self-pin sweep finds it; `--plan` prints the packages by layer from the catalog table. An install that fails `ERESOLVE` names the rerun command, and `--regenerate` replaces the lockfile and `node_modules` from the manifest under the refusals and proof [wave.md](references/wave.md) § Regenerate a lock the install cannot move states; `record` commits the overwrite's writes as `Overwrite with scaffold VERSION`, then paths dirtied only by that invocation's successful `format` step as `Format with oxfmt VERSION`, reading the formatter version from the target's installed manifest and attributing paths from dirty sets collected immediately before and after formatting; it refuses every other dirty path by name before committing. On `--from record`, it reports the absent format evidence and commits only the overwrite receipt's paths and the manifest pair. The visit runs the target's own executable as scaffold only when the target's manifest names `@orkestrel/scaffold`, and otherwise refuses, naming the install the target needs. Exit 0 when every step passed, 1 when one failed, 2 when a reading failed, 64 on usage, including `--regenerate` with `--plan`. |
|
|
30
|
-
| `scripts/window.ts` | `--whoami [--wait SECONDS]` reads or polls `npm whoami`; `--login` prints the operator's login command and polls `whoami` until it answers; `--publish DIR... --otp CODE` refuses a batch whose nearest `.git` entry is a file, including ancestor entries, with exit 3 before contacting npm; it names a linked worktree's primary clone or identifies a submodule, then uploads back to back with `npm publish --ignore-scripts --otp`, journals each upload under `tmp/units/`, stops at the first refusal naming where to resume, and confirms each accepted version against the registry; `--confirm NAME@VERSION...` re-reads the registry until it serves the version. Exit 0 on success, 3 when not, 64 on usage.
|
|
24
|
+
| Script | Does |
|
|
25
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| `scripts/compare.ts` | `[--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]`, run from the package root after its build: fetches the published tarball and lists the material differences from the rebuilt `dist/` (sourcemaps excluded, whitespace-only differences ignored). Exit 0 when nothing differs, 3 when something does, 2 when the tarball cannot be read, 64 on usage (no package name, no `dist/`, or `--tarball` with no path). |
|
|
27
|
+
| `scripts/pins.ts` | `--version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests,guides] [--json]`, run from the package root: lists every line under the paths (`src`, `tests`, and `guides` by default) carrying the prior version literal or a prior range literal, once per line, sweeping a one-comparator range such as `^8.3.0` for its bare version in any form. Exit 0 with no hits, 3 with hits, 64 on usage (no literal, or a flag with no value). |
|
|
28
|
+
| `scripts/swap.ts` | One mode per run, from any directory: `--pin --consumer DIR --source DIR [--source DIR ...] [--override NAME ...] [--no-build] [--dry-run] [--json]` refuses a source whose packed manifest names a local dependency spec in any dependency field (a `file:` or `link:` prefix, a path start of `.`, `~/`, `/`, `\`, or a drive letter, or a protocol-free archive name ending in `.tgz`, `.tar.gz`, or `.tar` that is not a `user/repo` shorthand), builds and packs each source into `<consumer>/tmp/tarballs/` under a name carrying its SHA-256, records each replaced range in the ledger `pins.json` there, the record of which build the consumer runs, writes each tarball's absolute `file:` spec and each `--override` (repeatable, like `--source`) where oxfmt sorts it, installs, and proves that every pinned source, an override-only one included, is installed with the source's bytes; `--restore --consumer DIR [--package NAME ...] [--json]` puts back each recorded range and override, keeps an `overrides` block that existed before the pin, installs, proves the restored copy, and lists the re-pin arguments, and refuses with 64, before it writes anything, a ledger whose package or override keys are not package names or whose removal would leave `node_modules`; `--status --consumer DIR [--json]` writes nothing and reports drift between the ledger, the manifest, the tarballs, the installed bytes, and the source commits, a manifest spec holding its tarball only when it names the ledger archive's location. `--pin` and `--restore` write a receipt under `tmp/units/`. Exit 0 on success, 1 when a command or a proof failed, 3 when `--status` reports drift, 64 on usage. |
|
|
29
|
+
| `scripts/wave.ts` | `--visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE]` runs one repository's visit in the order [wave.md](references/wave.md) § Visit a repository fixes (pin, commit, overwrite, verify, install, pins, format, record, gates, compare), stops at the first failing step, journals each executed step's full output under the target's `tmp/units/wave/` when the work tree ignores `tmp/` and names the journal in its row, and prints each step's exit (a failed step names the `code: message` refusal or the `note` a JSON verb writes on stdout, else the last stderr lines), the bump ruling (the rebuilt dist against the published tarball, and the final runtime dependency set against the published manifest), and a row for `.orkestrel/release.md`; `--prior` names the version a pre-ruled bump replaced so the self-pin sweep finds it; the `pins` step sweeps every range that moved since that version's `Release <version>` commit as well as every range the visit moved, and a run that executes the sweep names its source in the row; `--plan` prints the packages by layer from the catalog table. An install that fails `ERESOLVE` names the rerun command, and `--regenerate` replaces the lockfile and `node_modules` from the manifest under the refusals and proof [wave.md](references/wave.md) § Regenerate a lock the install cannot move states; `record` commits the overwrite's writes as `Overwrite with scaffold VERSION`, then paths dirtied only by that invocation's successful `format` step as `Format with oxfmt VERSION`, reading the formatter version from the target's installed manifest and attributing paths from dirty sets collected immediately before and after formatting; it refuses every other dirty path by name before committing. On `--from record`, it reports the absent format evidence and commits only the overwrite receipt's paths and the manifest pair. The visit runs the target's own executable as scaffold only when the target's manifest names `@orkestrel/scaffold`, and otherwise refuses, naming the install the target needs. Exit 0 when every step passed, 1 when one failed, 2 when a reading failed, 64 on usage, including `--regenerate` with `--plan`. |
|
|
30
|
+
| `scripts/window.ts` | `--whoami [--wait SECONDS]` reads or polls `npm whoami`; `--login` prints the operator's login command and polls `whoami` until it answers; `--publish DIR... --otp CODE` refuses a batch whose nearest `.git` entry is a file, including ancestor entries, with exit 3 before contacting npm; it names a linked worktree's primary clone or identifies a submodule, then uploads back to back with `npm publish --ignore-scripts --otp`, journals each upload under `tmp/units/`, stops at the first refusal naming where to resume, and confirms each accepted version against the registry; `--confirm NAME@VERSION...` re-reads the registry until it serves the version. Exit 0 on success, 3 when not, 64 on usage. |
|
|
31
31
|
|
|
32
32
|
The user's current instruction wins. `references/release.md` binds every release: the credential and authorization law, the upload serialization, the tarball swap, what a bump obliges downstream, and the layer order. Nothing here weakens it. Where this skill disagrees with it, report the drift instead of following the skill.
|
|
33
33
|
|
|
@@ -71,7 +71,9 @@ Completion requires:
|
|
|
71
71
|
- every gate that proved a package ran outside the window and against the artifact that shipped;
|
|
72
72
|
- every gate red at a package's baseline for a cause `ROADMAP.md` already carries is recorded as a
|
|
73
73
|
standing reading beside the package's row with its carrier, and the release report names it. A
|
|
74
|
-
standing reading is not a gate the release ran
|
|
74
|
+
standing reading is not a gate the release ran;
|
|
75
|
+
- every standing host-bound reading with no `ROADMAP.md` item for its cause is recorded in
|
|
76
|
+
`.orkestrel/release.md`, and the release report names that cause for a `ROADMAP.md` item.
|
|
75
77
|
|
|
76
78
|
Report the layers in publish order, each package with its registry-confirmed version, the bump
|
|
77
79
|
rulings and their evidence, the approvals the user granted, and anything still unpublished. End
|
|
@@ -30,11 +30,11 @@ When a consumer needs a dependency's unpublished source, to meet a defect that l
|
|
|
30
30
|
- A development `devDependencies` bump reaches nobody: re-pin, prove the gates green, commit to `main`; do not bump or publish.
|
|
31
31
|
- A development bump that moves the published artifact is a runtime bump. Prove the direction with the build: rebuild after the re-pin and run `node .agents/skills/orkestrel-publish/scripts/compare.ts`, which compares `dist/` against the published tarball on material content only. Exit 3 bumps and publishes that package, and its dependents follow the runtime rule.
|
|
32
32
|
- A `0.0.x` caret pins one exact release, so the fleet publishes in topological layer order derived from runtime `dependencies` and `peerDependencies` edges, never from a development edge.
|
|
33
|
-
- Read each package's version and layer from the catalog table in `.claude/agents/orkestrel.md`,
|
|
33
|
+
- Read each package's version and layer from the catalog table in `.claude/agents/orkestrel.md`, refreshed per [wave.md](wave.md) § Prepare a layer before sequencing a cascade. Never write a second order elsewhere.
|
|
34
34
|
|
|
35
35
|
## The scaffold surface
|
|
36
36
|
|
|
37
|
-
- After a package's first publish,
|
|
37
|
+
- After a package's first publish, refresh the catalog in the scaffold checkout per [wave.md](wave.md) § Prepare a layer and release scaffold, so the `surface` rule reads the package's guide from that release.
|
|
38
38
|
- When a `@orkestrel/guide` release refuses a guide form its parser read before, push each catalog package's conforming guide to that package's `main`, the releasing package's own included, before the scaffold release that carries the catalog refresh; the `surface` rule parses every hosted guide, a target's own among them.
|
|
39
39
|
- `scaffold` is a development dependency of every package, so it publishes on its own and propagates as files, never as a cascade. Each package builds against the published `scaffold`.
|
|
40
40
|
- `scaffold` ships `dist/host`, the vendored file set every target receives through `repair`. Bump and publish `scaffold` when any vendored byte or the set of vendored paths changes.
|