@orkestrel/scaffold 0.0.123 → 0.0.125
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-publish/scripts/steps.js +523 -0
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
- package/dist/bin/main.js +18 -18
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -1
- package/dist/host/agents/platforms/windows.md +9 -1
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
- package/dist/host/claude/agents/orkestrel.md +45 -45
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +3 -1
- package/dist/host/claude/rules/tests.md +3 -1
- package/dist/host/guides/agent.md +349 -244
- package/dist/host/guides/brief.md +52 -48
- package/dist/host/guides/browser.md +2 -2
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/interpret.md +531 -155
- package/dist/host/guides/mcp.md +183 -61
- package/dist/host/guides/ndjson.md +47 -34
- package/dist/host/guides/ollama.md +123 -66
- package/dist/host/guides/program.md +117 -39
- package/dist/host/guides/qualifier.md +110 -59
- package/dist/host/guides/rater.md +85 -32
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +20 -12
- package/dist/host/guides/study.md +580 -483
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/guides/toolbox.md +159 -80
- package/dist/host/guides/workflow.md +44 -25
- package/dist/host/manifest.json +41 -35
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +10 -6
- package/dist/src/server/index.d.ts +10 -6
- package/dist/src/server/index.js +23 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +17 -17
|
@@ -91,10 +91,12 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
91
91
|
- Keep valid receipts. Re-run a check only when a change to its inputs, configuration, environment, or claim could alter what it proved, and then run the narrowest check that covers the change. Never repeat a passing check to collect another receipt or to have every suite pass in one command; name the receipt that covers each check a brief does not rerun.
|
|
92
92
|
- Ask the user only for a decision that is theirs: scope, the spend ceiling and stop line § Hold the plan names, a conflicting ruling, a credential, publication, or a commit or push the law reserves. Decide routine matters yourself, such as time and lane allowances, retries, and order, and report them, with time in whole minutes.
|
|
93
93
|
- Never end a turn with work pending and nothing that will wake the session: run the work as a tracked background command or a child whose completion notifies, or schedule a wake. While a lane runs, continue independent work.
|
|
94
|
+
- When nobody is awake to answer and a session waits on a child, arm a keep-alive and a limit on the wait, and name a peer session as the watchdog.
|
|
94
95
|
|
|
95
96
|
## Hold the plan
|
|
96
97
|
|
|
97
98
|
- Open with the goal and acceptance criteria per `AGENTS.md` § Work loop, then estimate the scope: the units, the review and evidence each needs, and what stays out. When the estimate is large, agree with the user the estimate, the spend ceiling, and the stop line: how much lane time the work can take, and the point at which work stops and reports. Derive an estimate or a process cap from a measurement of the same command, execution shape, and toolchain, and state that measurement beside the figure, or state that none exists.
|
|
99
|
+
- When a measurement has more than one arm, price each arm in lane hours before ruling it in, and put that table first in the report that asks for the ruling.
|
|
98
100
|
- Before each unit, name the plan step it serves. Cut a unit no step needs; set an unplanned idea aside in the plan and return to the step.
|
|
99
101
|
- Add a tracked file only where the request, the plan, or a rule names it.
|
|
100
102
|
- After every unit return, unexpected result, or user message, compare the work with the plan: mark what is done, restate the next step, and set aside what no longer serves the goal.
|
|
@@ -107,6 +109,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
107
109
|
- Size the effort to the task before spending: a lookup takes one lane, routed per § Routing, and only open-ended work with independent, high-value parts fans out, per § Parallelism.
|
|
108
110
|
- Locate the evidence with short broad probes before any deep pass: a run of the shipped command, a census, a search. Go deep only on a defect or gap a run has shown, in one lane, with the narrowest instrument that answers it: a counting probe or a mutation.
|
|
109
111
|
- When a defect class can recur across packages, census the class across every package before a review of any one: a script lists the whole population, `scout` marks each listed row against the brief's explicit criteria, and `analyst` or the Orchestrator rules each marked row once and fixes it at its cause. A list made by hand is no population.
|
|
112
|
+
- Define a class in a census by what the code does, never by how it spells it. Where a baseline build exists, run a seeded differential against it over the repair's input domain, and report a search's hits as a floor, never as the class.
|
|
110
113
|
- Set every stop with what reopens it, and record both in the plan. At a re-examination, hold the stop unless a proposal names the condition it meets; a stop that names no condition passes only on the user's ruling. Before a continuation, record whether its unit repairs an admitted row or reopens the stopped seam.
|
|
111
114
|
- When a failure recurs, read the exact input and output of the failing case before adding capability, and fix the cause.
|
|
112
115
|
- Deepen in rounds and report a usable result after each. Stop at the first result that clears the acceptance criteria and name the gaps that remain.
|
|
@@ -129,6 +132,7 @@ The harness's own engine orchestrates: Claude Fable 5.1 or Claude Opus 5.5 in Cl
|
|
|
129
132
|
|
|
130
133
|
- Never run a review on a small change. Never run a second design round on the same brief. A design question a repair round opens is its own brief, not a second design round on the campaign's brief.
|
|
131
134
|
- A review judges types, tests, and implementation. It reports comment, TSDoc, or guide wording only where the text contradicts the final behavior, and no fix round opens for prose alone.
|
|
135
|
+
- When a brief restates a ruling, give the reviewer the ruling's own text beside the brief, and make any disagreement between the two a claim.
|
|
132
136
|
- Before a repair is dispatched, class its remedy as a correction, a design question, or a deferral; a remedy that adds a mechanism (a file operation, a state, a protocol step, or a retry class) is a design question that goes to one `planner` or `analyst` pass carrying measured platform facts.
|
|
133
137
|
- A fix round re-audits the repaired claim only. A fix that departs from the reviewer's prescription gets one pass by an independent reviewer per § Engines.
|
|
134
138
|
- Every repair, a prescription adopted verbatim included, closes with a mutation probe on its load-bearing line (disable it, watch the test fail, restore it); `node .agents/skills/orkestrel-falsify/scripts/mutate.ts --edits EDITS.md -- COMMAND` runs the probe and proves the restore. Where the repair adds or changes a process proof, the proof's repeat run under suite load closes it too.
|
|
@@ -185,7 +189,7 @@ Every working file lives under the checkout's gitignored `tmp/`, in the director
|
|
|
185
189
|
| `tmp/claude/`, `tmp/codex/`, `tmp/cursor/` | bench briefs, launch scripts, journals, `.err` files, last-message files, login logs, per harness |
|
|
186
190
|
| `tmp/units/` | native unit briefs, reports, claims files, and unit records |
|
|
187
191
|
| `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/`) |
|
|
188
|
-
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe`
|
|
192
|
+
| `tmp/type/` | the type stage's workspace mirror, owned by `@orkestrel/probe`; from probe 0.0.28 on, it carries `tmp/probes` and nothing else under the root `tmp/` |
|
|
189
193
|
| `tmp/captures/` | screenshots, Vitest's `page.screenshot()` captures under `screenshots/` included, resolved-style snapshots, and other capture portfolios |
|
|
190
194
|
| `tmp/browsers/` | the journeys a `browse` server saves, their runs and captures, and its profiles under `.profiles/` |
|
|
191
195
|
| `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 |
|
|
@@ -4,8 +4,9 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
|
|
|
4
4
|
|
|
5
5
|
## Processes
|
|
6
6
|
|
|
7
|
-
- Before `npm ci`,
|
|
7
|
+
- Before `npm ci`, and when a chain starts rather than when its plan was written, test each `.node`, `.dll`, and `.exe` file under the checkout's `node_modules` with a write-mode open: `openSync(path, 'r+')`, closed immediately, writes no byte, and a loaded image refuses with `EBUSY` (read 2026-11-05: it refused the 2 of 5 files a live `probe` server and its `oxlint --lsp` child held, and opened the other 3). `.agents/skills/orkestrel-publish/scripts/steps.ts` runs this read. When a file refuses, skip `npm ci` and recover per the following bullet.
|
|
8
8
|
- When a held file under `node_modules` blocks or interrupts an install, identify its holders, terminate no process the session did not launch, and record the partial installation state. Rebuild from the unchanged lockfile with `npm install`, verify the manifest and lockfile identities and the tree with `npm ls --all`, and report the clean-install criterion the recovery did not prove.
|
|
9
|
+
- Name a holder from a process's `Modules` list, and rule nothing from it or from `tasklist /M <file>.node`: `tasklist` matches by module name across every checkout, and a module list keeps the path a file loaded from after its tree moved. A session's `probe` MCP server and its `oxlint --lsp` child hold native files in the checkout they started in.
|
|
9
10
|
- Read liveness with `Get-Process -Id <pid>` in PowerShell, or under Git Bash from the output of `tasklist //FI "PID eq <pid>" //NH`: a row naming the pid means alive, and the `INFO:` line means gone. Never read liveness from `tasklist`'s exit code, `kill -0`, or `ps -eo`.
|
|
10
11
|
- List descendants with `Get-CimInstance Win32_Process -Filter "ParentProcessId=<pid>"`, applied to each listed id in turn. Under Git Bash, run it through `powershell -NoProfile -Command`, and write every Windows slash option as `//`.
|
|
11
12
|
- Kill a recorded tree with `taskkill /pid <pid> /T /F`. `launch.ts` kills the tree at its cap on this host.
|
|
@@ -15,6 +16,13 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
|
|
|
15
16
|
- Deliver a console Ctrl+C through `WScript.Shell` `AppActivate` then `SendKeys('^c')` after confirming activation when no computer-use tool is available.
|
|
16
17
|
- A `rename` onto a freshly hard-linked file can return `EPERM` while a scanner holds it.
|
|
17
18
|
- A child CLI can leak orphaned `conhost.exe` processes and open console windows. Count them with `Get-Process conhost` at each launch while such a lane is live.
|
|
19
|
+
- Before designing a fan-out, measure what one dispatched child costs in consoles with `Get-Process conhost` before and after it, and size the fan-out from that reading: a Codex child held four consoles on 2026-11-05, and a long-lived session costs a fixed number.
|
|
20
|
+
- Read free commit space beside the console count before a long measured run. A task's completion does not end its shell: a finished unit's PowerShell held 267 GB for 11 hours in `ConvertTo-Json -Depth 25`, leaving 1.5 GB of commit space (2026-11-05). Never run `ConvertTo-Json` over a live object graph; project the fields first.
|
|
21
|
+
|
|
22
|
+
## Git Bash
|
|
23
|
+
|
|
24
|
+
- Write `C:/` in every path Windows Node reads from inside a string, such as `node -e`: Git Bash translates a path argument and leaves a string alone, so `/c/Users/...` reads as `C:\c\Users\...`.
|
|
25
|
+
- Chain a command that gates the next with `&&`, because the command after `;` runs on a failure.
|
|
18
26
|
|
|
19
27
|
## PowerShell 5.1
|
|
20
28
|
|
|
@@ -27,7 +27,7 @@ description: >-
|
|
|
27
27
|
1. A small native unit's brief is the dispatch message: scope, law references, expected result. Otherwise run `node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit <unit> --lane <lane>` and fill every section; write `none` in an empty one. 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
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. Name each owned path with the rule that places it, preflight every path the unit will need once before the brief ships, and refuse a catch-all ownership line. A file grant authorizes no package: name each one the unit may add with the user's ruling. A brief that prescribes a mechanism step by step lists the inherited operations that keep their behavior, so its stop line guards only what the prescription changes.
|
|
30
|
-
4. Order acceptance criteria cheap-first, 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.
|
|
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. A brief that takes up a contract change names the release's whole `npm test`, because `&&` hides every suite after the first failure; after one fails, run the remaining suites independently. A brief on a hot path carries the cost bar `.claude/rules/quality.md` § Performance requires.
|
|
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. Word a review brief per `.claude/rules/writing.md` § Substitutions and the review-wording quirk in the `orkestrel-parallel` skill's reference Codex as a lane host.
|
|
@@ -9,6 +9,7 @@ Give every claims brief these rows.
|
|
|
9
9
|
- **Subject.** The whole chain, not the last commit: the tip, the branch, and one line per prior round on what it claimed to close.
|
|
10
10
|
- **What the round decides.** One sentence, such as "this decides whether the package is bumped and consumed downstream" or "this decides whether the fix is accepted".
|
|
11
11
|
- **Already established.** What the Orchestrator verified directly, so no lane re-derives it or re-reports it. State that the Orchestrator verified each item itself.
|
|
12
|
+
- **Rulings.** The text of each ruling the subject's briefs restate, per `.agents/orchestration.md` § Size gate.
|
|
12
13
|
- **Review evidence.** The actual diff and the actual `git status --porcelain` output, by path. For a rendered or externally driven surface, the capture; source is corroboration.
|
|
13
14
|
- **Numbered falsifiable claims.** Written to `tmp/units/<unit>-claims.md`, one file both lanes read. Each claim names a property a concrete input, state, or interleaving could show false, and the settling row `SKILL.md` § Write the claims requires. Assign a primary lane where the lanes differ in strength; no lane skips a claim. The claim set is the round's scope: cover what the subject owns, then hold it closed. A finding against something no claim names enters the verdict only when substantiated to the `BROKEN` standard; otherwise it is a claim for the successor brief.
|
|
14
15
|
- **Release bar.** The observable consequences that make a finding outside the claims enter the terminal line, or `none`; a brief that names none puts every substantiated outside finding there. In a harden campaign, the plan's bar.
|
|
@@ -27,6 +27,7 @@ Select the method for the package kind and scenario before choosing an instrumen
|
|
|
27
27
|
| Persistence or compaction | What has committed, and which marks govern resume? | Snapshot source marks after the result, preserve original logs, and state the different rollback boundaries of a plain fold and a later merge. § Preserve source history and name the real transaction boundary. |
|
|
28
28
|
| Instruction libraries | Is this wiring timing or a model's observed use? | Wiring timing: prove the next-run or fold effect with a scripted run; § Load instructions progressively and prove when they take effect. Observed use: run model-driven efficacy as a separate study; § Exercise the composed consumer early and match the claimed host; § Separate developmental evidence, confirmation, and answer-path quality. |
|
|
29
29
|
| Proof or review | Did the named assertion fail, did compilation alone fail, or did a file not run? | Keep failing-first, mutation, collection, restore, and independent receipts separate. § Prove an instrument's domain and its actual sensitivity; § Keep failing-first, mutation, restoration, and collection receipts distinct; § Reconcile evidence rather than reviewer votes. A mutant that hangs its own timer: § Use a terminating count to prove a synchronous bound. |
|
|
30
|
+
| Generated corpus or long measured run | Is each truth value on the right fact, is the run rehearsed, and is each arm priced? | Mark every row and plant swaps: § Prove truth assignment on a generated corpus. Rehearse first: § Rehearse a long run at full scale. Price arms before ruling them in: § Price each arm before ruling it in. |
|
|
30
31
|
| Study or custody | Is the claim freeze, grade, progress, replay, or next-request identity? | Prove the exact operation or entry and its control, and refuse a successful neighbor operation as a substitute. § Prove custody and the exact closure route before expensive use. |
|
|
31
32
|
| Learned reader or router | Is the candidate using metadata that ships, and does its fallback win where invoked? | Remeasure the shippable intervention: § Compare the shippable intervention, including what it loses. Charge costs: § Charge a learned decision for the decision itself. Keep the written comparison graph and infer no winner from disagreement: § Keep the committed comparison graph and the meaning of each metric. A reader that changes what it extracts: § Report extraction quality alongside latency. |
|
|
32
33
|
| Consumer migration | Is the consumer exhaustive, defaulted, indirect, or nested? | Census all forms and execute the defaulted or loaded path: § Audit a consumer migration beyond compiling names. Prove packed and registry identity separately: § Distinguish source revision, packed bytes, registry resolution, and publication. |
|
|
@@ -187,6 +188,24 @@ When model runs or labelers threaten to consume a cap before producing inspectab
|
|
|
187
188
|
- **Example.** `@orkestrel/agent` `no commit recorded`: “A profile value stopped the compaction arm, not a defect in Agent or Study”, and no successful fold comparison follows from that stopped arm.
|
|
188
189
|
- **Law.** `.agents/orchestration.md` § Hold the plan.
|
|
189
190
|
|
|
191
|
+
### Rehearse a long run at full scale
|
|
192
|
+
|
|
193
|
+
When a run will hold the host or a model for hours, rehearse it on the real frozen shape with real inputs and no model, let `verifier` run it and `checker` read its files, and read the rehearsal's own cost before the window opens.
|
|
194
|
+
|
|
195
|
+
- **Refuse.** A further review as readiness, because a review can find a stopper and cannot read the run's own cost: the re-audit found the `limit` spelling and four ids Study refuses, and the ruling there was no third review and a rehearsal. A rehearsal on a sized copy, because a quadratic term reads as nothing at a smaller scale.
|
|
196
|
+
- **Reading.** In the `@orkestrel/learn` package, on M3's harness: the re-audit measured a quadratic read that “adds about 15.6 hours”, and the rehearsal then read every message reaching a denominator and two scorers differing on 0 rows.
|
|
197
|
+
- **Example.** `@orkestrel/learn` `89e9c39`: the harness the ruling closed by rehearsal, after two reviews failed it.
|
|
198
|
+
- **Law.** `.claude/rules/quality.md` § Performance.
|
|
199
|
+
|
|
200
|
+
### Price each arm before ruling it in
|
|
201
|
+
|
|
202
|
+
When a ruling would add an arm, a reader, or a person to a measurement, state its lane hours before ruling on it, and keep a priced table at the head of the report that asks for the ruling.
|
|
203
|
+
|
|
204
|
+
- **Refuse.** A run of rulings with no running total, because each one sounds reasonable and only the total is the cost. A kept arm no question needs, because an arm's cost is paid whether or not its reading decides anything.
|
|
205
|
+
- **Reading.** In the `@orkestrel/learn` package, on M3: after the cut to three arms, the scored run read “1.16 h against a 4-hour cap”.
|
|
206
|
+
- **Example.** `@orkestrel/learn` `89e9c39`: the harness cut to three arms after the user asked “what are we even doing and do we really need to?”.
|
|
207
|
+
- **Law.** `.agents/orchestration.md` § Hold the plan.
|
|
208
|
+
|
|
190
209
|
### Charge a learned decision for the decision itself
|
|
191
210
|
|
|
192
211
|
When a learned router beats a threshold in prediction quality, check semantic permission before cost selection, compare paired regret and accuracy with threshold and fixed routes, repeat fresh sessions and out-of-range populations, test a unit-invariant target with controls that challenge the objective, and state which comparisons are predeclared.
|
|
@@ -454,11 +473,20 @@ When an expensive use depends on a freeze, a grade, progress, a replay, or next-
|
|
|
454
473
|
|
|
455
474
|
When a study reports a measurement, hold the populations apart as the law states, fit preprocessing only on training data, measure accepted wrong, latent wrong, useful coverage, and the answers-only user's final decision, run helpful correction as a separate scenario, keep unknown, unselected, and unreached distinct, and replace a changed subject's assertions.
|
|
456
475
|
|
|
457
|
-
- **Refuse.** An old green result carried to a changed subject, because “none survives as a proof”. A labeling floor as a quality control, because that floor “cannot fail”. A label disagreement on equal products as a product difference, because that disagreement “is the labelers' own”. Semantic substitution from a lexical score, because its correlations did not earn that substitution. A population audit that asserts counts alone, because every count can hold while strata fail to cross, one value dominates, boundary values land together, or a ceiling under the bar makes the run measure the grid: in `@orkestrel/learn`, every count holds while all 200 ordinary messages are approvals and one pair of boundary values sits on 202 of 600 subjects.
|
|
476
|
+
- **Refuse.** An old green result carried to a changed subject, because “none survives as a proof”. A labeling floor as a quality control, because that floor “cannot fail”. A label disagreement on equal products as a product difference, because that disagreement “is the labelers' own”. Semantic substitution from a lexical score, because its correlations did not earn that substitution. A population audit that asserts counts alone, because every count can hold while strata fail to cross, one value dominates, boundary values land together, or a ceiling under the bar makes the run measure the grid: in `@orkestrel/learn`, every count holds while all 200 ordinary messages are approvals and one pair of boundary values sits on 202 of 600 subjects. An audit with no negative control, because an audit proves itself by refusing the draw it was written to reject, so rerun it on the prior draw, per `.claude/rules/quality.md` § Instruments. A sum of sole-blocker rows as a bound, because removing one blocker changes which rows the others block and can add wrong rows: report each removal's row-level right and wrong, as `@orkestrel/learn` read `Superseded` gaining 126 right and adding 0 wrong and `Support` gaining 5 right and adding 1 wrong.
|
|
458
477
|
- **Reading.** In the `@orkestrel/learn` package, on its study: “only the rubric contains population membership and expected outputs”. The answers-path scenario stays a specification, not a completed result, and no completed carrier is recorded.
|
|
459
478
|
- **Example.** `@orkestrel/learn` `a6a25c4`: the removal of the regression study held at historical commit `87a6463`, because the subject changes and its assertions no longer apply.
|
|
460
479
|
- **Law.** `.claude/rules/tests.md` § Expensive proofs.
|
|
461
480
|
|
|
481
|
+
### Prove truth assignment on a generated corpus
|
|
482
|
+
|
|
483
|
+
When a generated corpus carries truth into a measurement, mark every row for which fact each value sits on, with planted swaps and other wrong rows as the marker's controls, read the first messages before the run, and compare the writer packet's wording with whatever the reader's prompt is built from.
|
|
484
|
+
|
|
485
|
+
- **Refuse.** A fact check that finds a value as proof the value is on the right fact, because presence is not assignment. A sample where one swap moves the bar, because a swap at half a point moves a safety bar, so census every row. A packet whose fact labels repeat the reader's field descriptions, because a coverage number from that packet says little. A further wording round after a redraw, because that round tunes the writer against the reading hoped for.
|
|
486
|
+
- **Reading.** In the `@orkestrel/learn` package, on M3's census: all 1,800 main rows marked, with planted `swap` 20 of 20, `absent` 5 of 5, `revision` 5 of 5, and `missing` 0 of 5 on `scout` and 5 of 5 on `astra`.
|
|
487
|
+
- **Example.** `@orkestrel/learn` `f9097df`: the corpus and census record, after a first packet was superseded unread by any reader.
|
|
488
|
+
- **Law.** `.claude/rules/quality.md` § Instruments.
|
|
489
|
+
|
|
462
490
|
### Audit a consumer migration beyond compiling names
|
|
463
491
|
|
|
464
492
|
When a consumer migration compiles, census direct and indirect vocabulary, materialized fixtures, exhaustive switches, and defaulted branches, load the entry that resolves the disputed dependency, compare a clean published consumer, and keep recorded version strings unchanged where they describe evidence.
|
|
@@ -483,7 +511,7 @@ When shorthand compiles to an existing execution engine, derive only entailed de
|
|
|
483
511
|
|
|
484
512
|
When findings keep coming package by package, ask whether they are breadth or depth; for depth, reproduce the actual case and ask a design question when the class recurs; for a class that recurs across packages, run the census the law fixes before any reader marks a row, probe representation-aware pairs and their reachable public consequences, read the result as causes, prove each cause reachable through a public call before opening a row, repair the owning mechanism in one consumer, and spread the repair dependency-first.
|
|
485
513
|
|
|
486
|
-
- **Refuse.** A raw split count as separate fixes, because distinct splits reduce to fewer causes. A hand list as exhaustive coverage, because hand enumeration missed rows. A catch-to-empty traversal as coverage proof, because complete enumeration remains the requirement. A common instrument as each package's semantic oracle, because cross-package promotion and standing local assertions are complementary.
|
|
514
|
+
- **Refuse.** A raw split count as separate fixes, because distinct splits reduce to fewer causes. A hand list as exhaustive coverage, because hand enumeration missed rows. A catch-to-empty traversal as coverage proof, because complete enumeration remains the requirement. A common instrument as each package's semantic oracle, because cross-package promotion and standing local assertions are complementary. A search by spelling as the class, because in `@orkestrel/interpret` a search for `.at(-1)` and its kin read one site while the same last-wins sat in a fold that a seeded differential against the baseline found.
|
|
487
515
|
- **Reading.** On the census of the family of packages around `@orkestrel/contract` and `@orkestrel/reason`, `no commit recorded`: hand lists of 21 and 14 against 91 pairs, then all 279 marked from a script. No one commit owns the census method.
|
|
488
516
|
- **Example.** `@orkestrel/contract` and `@orkestrel/reason` `no commit recorded`: a ruling on causes before repair, where “Tightening runtime guards would have been wrong for most splits”.
|
|
489
517
|
- **Law.** `.agents/orchestration.md` § Depth, breadth, and machinery.
|
|
@@ -118,6 +118,7 @@ expect: <red or green, named cases, required artifact>
|
|
|
118
118
|
Apply this section when two sessions on one machine share the tests, checks, builds, and captures the host can run at once.
|
|
119
119
|
|
|
120
120
|
- Run each process-running command through `scripts/lane.ts`, which orders the commands across sessions, and send no handover message. On its exit 75 or 70, report its standard error line to the user and start no process-running command.
|
|
121
|
+
- Pass the command to `scripts/lane.ts` directly after `--`, never through `bash -c`: a background child under `bash` can survive the forced kill with a parent that names neither the launcher nor the command, and the next arrival then overlaps it.
|
|
121
122
|
- When a host's sessions run another serializer, keep using it until a scaffold release carries `scripts/lane.ts` and no command runs on the host, then move every caller in one step, because a second queue does not see the first.
|
|
122
123
|
- While another session holds the lane, edit your own files, read, and queue your commands. Set no clock windows and send no per-command acknowledgments.
|
|
123
124
|
- Class contention from another session per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief. Rerun the interrupted unit alone after the window clears.
|
|
@@ -10,7 +10,7 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
|
|
|
10
10
|
| Continue | Send an ordinary continuation to the child's `childThreadId` through `t3_thread_send`: `queue` for a separate request turn, `auto` for a reply or idle continuation, `steer` only for an in-flight change. Send a continuation that changes scope, acceptance, or authorization as a pointer to its `<unit>-brief-<n>.md`; send a bare message only for an unchanged objective. |
|
|
11
11
|
| Wake versus deliver | An async child's completion wakes the parent thread with a notification. A queued turn can finish with no notice (2026-10-23). |
|
|
12
12
|
| Track | The full `taskId` the launch returns, the `childThreadId`, and the provider, model, and options actually applied. The `clientRequestId` is no lookup key. Thread ids change when the tool session changes, sometimes between launches. |
|
|
13
|
-
| Background | A child runs commands through its provider's shell. T3
|
|
13
|
+
| Background | A child runs commands through its provider's shell, and a task's completion does not end that shell. T3 stopped an idle provider session's process tree about 30 minutes after its last turn on 2026-10-15; on 2026-11-05 finished Codex children still held their `probe` servers at 54 minutes, and `task_cancel` and archiving left them running. |
|
|
14
14
|
| Isolation | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits. |
|
|
15
15
|
| Tools | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22). |
|
|
16
16
|
| Limits | A provider's usage limit acts as that provider's page states. T3 refuses delegation with `parent_not_active` while the parent thread is not active (2026-10-24); the Background row holds the idle stop. |
|
|
@@ -24,6 +24,10 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
|
|
|
24
24
|
- When an ordinary follow-up starts, use a stable `clientRequestId` and retain the returned task id beside, never in place of, the original result. A completed task and a later turn in its child thread are distinct results.
|
|
25
25
|
- When a queued turn's result is needed and no notice came, read the durable result file or `task_status` with the full task id once.
|
|
26
26
|
- When a launch's reply is missing or ambiguous, inspect the recorded task before retrying. A timeout on a parent wait cancels no child work.
|
|
27
|
+
- When a send carries a consequential message, use `auto` and read the target to confirm it arrived: a `queue` send reported as queued, on a run that had already completed, never reached its target (2026-11-05).
|
|
28
|
+
- When a child's status reads completed, read its thread and the process list before acting on that status: its background shell can wake it for another turn. Check a child's claim about its own shell the same way (2026-11-05).
|
|
29
|
+
- When a finished child still holds servers past the idle stop, stop them by recorded process id, and read `.agents/platforms/` for what each child costs on the host.
|
|
30
|
+
- When a thread shows a nonzero `pendingRequestCount` and `t3_pending_request` lists nothing, read it as an approval nobody can answer, because that tool lists no approvals (2026-11-06).
|
|
27
31
|
- When a lane must be interrupted and restarted, use `restart`; never use it as a resume. Create no ordinary top-level thread as a delegated lane.
|
|
28
32
|
- When a child task starts, carry its charter's limits in the brief, the refusals to commit and install included: a child's tools are unrestricted whatever its charter's frontmatter lists, so a charter binds only through its brief (2026-11-04).
|
|
29
33
|
- When a child would launch processes beside another, get the user's go-ahead until a quiet single-lane trial passes on that host.
|
|
@@ -25,6 +25,7 @@ description: Run an Orkestrel release from layer order to registry confirmation,
|
|
|
25
25
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
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
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/steps.ts` | `--journal DIR [--omit NAME=REASON ...] [--no-ci] [--dry-run] [--json]`, run from the package root: derives the release chain from `prepublishOnly`, refusing any segment but `npm test`, `npm run NAME`, and `npm run NAME -- ARGS...` and any repeated step name, opens the plan with `ci` and `clean`, writes `plan.json` and `omitted.txt` to the journal, and runs it through `.agents/skills/orkestrel-dispatch/scripts/chain.ts` with `npm_config_prefer_online=true`. `--omit` (repeatable) leaves one derived step out for a stated reason, `--no-ci` leaves `ci` out, and on Windows `ci` is left out when a `.node`, `.dll`, or `.exe` file under `node_modules` refuses a write-mode open at chain start. `--dry-run` prints the steps and omissions, writes nothing, and runs nothing, and `--json` makes that print one JSON value. Exit with the chain's code (a step's exit passes through, so a step exiting 65 reads alike), 2 when a step or the chain cannot start or the journal cannot be written, 64 on usage, 65 when no complete step list can be derived or an `--omit` names no derived step. |
|
|
28
29
|
| `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
30
|
| `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
31
|
| `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. |
|
|
@@ -5,7 +5,7 @@ The `orkestrel-publish` skill names this file. It carries the fleet release rule
|
|
|
5
5
|
## Publishing is the user's
|
|
6
6
|
|
|
7
7
|
- Publishing is the user's decision and the user's credential. Prepare, surface the approval, and run the publishes the user asked for. Never substitute an API key, an access token, a copied auth file, or another login flow, and never ask the user to paste a token into the conversation.
|
|
8
|
-
- A publish chain is a long-running command:
|
|
8
|
+
- A publish chain is a long-running command: run it through `scripts/steps.ts`, which derives its plan for the `orkestrel-dispatch` skill's `scripts/chain.ts`, and launch that through that skill's `scripts/launch.ts`; confirm the previous chain is dead by process id before starting another. Publish serially; concurrent publishes collide on the authentication handshake.
|
|
9
9
|
- A wave over unpublished tips derives its order per run from the dependency graph and records only the round each package landed in.
|
|
10
10
|
|
|
11
11
|
## Fix a dependency before it publishes
|
|
@@ -17,7 +17,7 @@ When a consumer needs a dependency's unpublished source, to meet a defect that l
|
|
|
17
17
|
- Keep the absolute `file:` spec the script writes. npm resolves a relative spec against the installed package's own directory, so a packed consumer installed elsewhere, as the `distribution` proof installs it, cannot find a relative tarball.
|
|
18
18
|
- Pass `--override <name>` for each pinned package that another installed package also requires. The override is `$<name>` when the consumer declares the package and the tarball spec when it does not. The proof fails a pin that leaves a pinned package, an override-only one included, uninstalled at the top level, that leaves a second copy of a pinned package, or that moves an unpinned `@orkestrel` package; an override that selects no installed dependency is such a failure and exits 1.
|
|
19
19
|
- Run `scripts/swap.ts --status --consumer <consumer>` before relying on any gate run against a pinned consumer. Exit 3 names each drift: a manifest entry that no longer names the full location of its ledger tarball (a relative spec that resolves to that location holds it), a missing or changed tarball, installed bytes that differ from the proved pin, a pin with no proved install, or a source whose commit moved. Re-pin to clear it.
|
|
20
|
-
- Re-pin whenever the dependency's source moves; a stale tarball is a stale `dist/`. Fetch and merge the dependency's default branch before packing it.
|
|
20
|
+
- Re-pin whenever the dependency's source moves; a stale tarball is a stale `dist/`. Re-pack a consumer's whole pinned set together and read the tree for a second copy, because a partial re-pack nests the registry's older copies of what the rest depend on. Fetch and merge the dependency's default branch before packing it.
|
|
21
21
|
- Delete the consumer's `node_modules/.vite` directory after every tarball install the script does not run, or install into a fresh worktree; Vite keys its pre-bundle on the installed version, and the script deletes it after its own installs.
|
|
22
22
|
- Run one unit per checkout, at that checkout's catalog layer.
|
|
23
23
|
- Restore with `scripts/swap.ts --restore --consumer <consumer>` before any `scaffold` verb, before any gate that must see a registry range or prove the published artifact, and before publishing anything. The restore puts back each recorded range, keeps an `overrides` block that existed before the pin and removes one the pin created, removes the lock entry and installed copy of each restored package and dropped override so the install resolves them again from the registry, and proves the registry source in the lockfile. The restore refuses with exit 64, before it writes anything, a ledger whose package or override keys are not package names or whose removal would leave `node_modules`. [wave.md](wave.md) § Visit a repository orders a verb run around the pins.
|
|
@@ -19,7 +19,8 @@ overwrite receipts are written only where the work tree ignores `tmp/`.
|
|
|
19
19
|
blueprint plans in those sections; exclude the fixed showcase tool pair from ordinary release lookups.
|
|
20
20
|
Look up fleet releases with `*`; look up foreign tools with
|
|
21
21
|
a caret over the declared major when one can be extracted, otherwise with the declared range.
|
|
22
|
-
Do not treat a declared minor or patch bound as the lookup bound.
|
|
22
|
+
Do not treat a declared minor or patch bound as the lookup bound. A lookup skips a deprecated
|
|
23
|
+
version, and skips a version above `latest` when the range is `*` or sits in `latest`'s major. Peer-only dependencies produce no release reading;
|
|
23
24
|
rewrite a peer range only when its name shares an audited release reading. For example, with
|
|
24
25
|
peer-only `@orkestrel/peer-only: ^0.0.1`, leave that peer unchanged; with a planned tool whose
|
|
25
26
|
registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though the tilde excludes `8.3.4`.
|
|
@@ -139,7 +140,9 @@ moving the lockfile in place. Without the flag, the step deletes nothing.
|
|
|
139
140
|
tree; a failed result restores the copied lockfile and moved tree and names why the step failed.
|
|
140
141
|
Confirm a recoverable tree and lock backup before deleting the active tree. Attempt rollback at
|
|
141
142
|
most once. If rollback fails, retain both backup paths for recovery. If completion journaling or
|
|
142
|
-
backup cleanup fails, report that failure and retain the restored or proved installation.
|
|
143
|
+
backup cleanup fails, report that failure and retain the restored or proved installation. A file a
|
|
144
|
+
process holds in the moved tree leaves the step's exit at 0 and its note names both backup paths
|
|
145
|
+
and the code; every other cleanup failure exits 1. Recycle a retained tree after its holder exits.
|
|
143
146
|
- Resume a visit that stopped at the refusal with `--regenerate --from <step>`.
|
|
144
147
|
|
|
145
148
|
## Rule on the bump
|
|
@@ -175,7 +178,9 @@ registry copy over any staged tip, so every consumer stays red until that tip is
|
|
|
175
178
|
- In scaffold's own layer, run `scaffold catalog --all`; track each mirror it adds with `git add`; add each added mirror's path to the declared vendored inventory in `tests/distribution.test.ts`; then run `npm run build`, so `host.json` records the refreshed files' digests, and then `scaffold surface --from .`.
|
|
176
179
|
- In the scaffold release that opens a transfer under `.claude/rules/names.md` § Fleet name ownership rule 5, declare it in `SURFACE_TRANSFERS` before `npm run build`. In the scaffold visit that closes it, remove the declaration before the build and confirm `host.json` no longer records the name.
|
|
177
180
|
- When `scaffold surface` prints an advisory, rule it under `.claude/rules/names.md` § Fleet name ownership before the upload; an advisory never stops the upload.
|
|
178
|
-
-
|
|
181
|
+
- Run each release chain through `node .agents/skills/orkestrel-publish/scripts/steps.ts --journal <dir>`, whether it runs in a clone or the checkout, and write no plan by hand. It derives the steps from `prepublishOnly`, opens with the clean reinstall and the clean, and leaves out `npm ci` when a native file under `node_modules` is held when the chain starts.
|
|
182
|
+
- Name a step a host cannot run with `--omit <name>=<reason>`, and quote every line of `<dir>/omitted.txt` in the release commit.
|
|
183
|
+
- Before writing a release commit, read the package's previous `Release` commit for the version stamps and host readings it carries.
|
|
179
184
|
- When a writer owns a script the preparation needs, run its installed built twin and record the executable's identity.
|
|
180
185
|
- Derive each release row's ruling from the measured distribution comparison and final runtime-range result under § Rule on the bump.
|
|
181
186
|
- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor.
|
|
@@ -195,7 +200,7 @@ Prepare a published package's layer in this order, after the visit has ruled the
|
|
|
195
200
|
preparation commit already precedes the overwrite; this install regenerates the lockfile for the
|
|
196
201
|
bumped manifest.
|
|
197
202
|
3. **Sweep the self-pins**, per the following section: the bump moves the version class.
|
|
198
|
-
4. **Run `prepublishOnly` to green on the candidate commit, in a fresh clone or, where the user rules clones out, in the checkout, in the order the package's own chain fixes.** Run every release step whose inputs remain valid after a failure and report each result. Before using a serial chain that stops on failure, split aggregate commands into their component steps and record each step's prerequisites. After a failure, run the independent steps in separate chains, mark dependent steps blocked, and keep the release result failed while a required step fails or remains blocked.
|
|
203
|
+
4. **Run `prepublishOnly` to green on the candidate commit, in a fresh clone or, where the user rules clones out, in the checkout, in the order the package's own chain fixes.** Run every release step whose inputs remain valid after a failure and report each result. Before using a serial chain that stops on failure, split aggregate commands into their component steps and record each step's prerequisites. After a failure, run the independent steps in separate chains, mark dependent steps blocked, and keep the release result failed while a required step fails or remains blocked. `steps.ts` stops at the first failure, so after one, rerun it under a distinct journal with `--no-ci` and `--omit <name>=<reason>` for each step already read except `build`, because `clean` still runs and a later step reads `dist/`, and run the suites of an aggregate step such as `npm test` as single commands.
|
|
199
204
|
Run this chain and the visit's gates on the newest release of the lowest Node major the
|
|
200
205
|
package's `engines.node` admits, on a Node whose bundled npm meets the `MINIMUM_NPM_VERSION`
|
|
201
206
|
floor a generated workspace declares in `devEngines`, launched under the `PATH` the
|
|
@@ -234,6 +239,10 @@ re-pin install, not after the manifest edit.
|
|
|
234
239
|
A canned packument in a fixture and a looked-up version in a CLI suite carry the version with no
|
|
235
240
|
tripwire comment beside them, and a generated-manifest fixture carries the ranges and never the
|
|
236
241
|
package's own version, so one run names both classes.
|
|
242
|
+
- Trace each hit through the constants and stubs before ruling it inert: a registry stub whose served
|
|
243
|
+
version derives from the manifest ties every test workspace range aligned with it, and a version
|
|
244
|
+
table in a package's distribution test ties each consumer it composes. Report ruled hits by class,
|
|
245
|
+
never as a bare count.
|
|
237
246
|
- Move a documented tripwire — a golden digest over generated output — in the same change as the
|
|
238
247
|
version bump. That is what the tripwire is for.
|
|
239
248
|
- Re-take a generated artifact's digest after the install, because the generated bytes can derive
|
|
@@ -252,6 +261,7 @@ name a version the registry already serves, so a dependency shipping in the same
|
|
|
252
261
|
resolvable previous pin and takes its development-only re-pin after the window closes. That re-pin
|
|
253
262
|
takes the self-pin sweep too, because the snapshot class moves with no bump.
|
|
254
263
|
|
|
264
|
+
- Before waiting on an upstream release, read its deprecation notice and its dist-tags.
|
|
255
265
|
- After a window confirms a release, poll its tarball URL, read with
|
|
256
266
|
`npm view NAME@VERSION dist.tarball`, until it answers `200` before an install names that
|
|
257
267
|
version. The registry lists a version in the packument minutes before it serves the tarball, and
|
|
@@ -268,10 +278,17 @@ package's own dependencies.
|
|
|
268
278
|
|
|
269
279
|
1. Take a registry sweep after the last window confirms. In every catalog package, list each
|
|
270
280
|
`devDependencies` range on an `@orkestrel` package that trails the release the sweep reads.
|
|
271
|
-
2. In each listed package, re-pin those ranges to the caret of the served release, install,
|
|
272
|
-
|
|
281
|
+
2. In each listed package, re-pin those ranges to the caret of the served release, install, run
|
|
282
|
+
`scaffold catalog` (`scaffold catalog --all` in the `@orkestrel/scaffold` checkout, per § Prepare a
|
|
283
|
+
layer) so the tracked mirrors and the table follow the re-pin, and sweep the self-pins per § Sweep
|
|
284
|
+
the self-pins, because the snapshot class moves with no bump.
|
|
273
285
|
3. Run the package's gates, then rule its bump under § Rule on the bump. Commit the re-pin of a
|
|
274
286
|
package the ruling leaves unbumped as `Re-pin <names> development ranges`; prepare and publish
|
|
275
287
|
each bumped package per § Prepare a layer, in layer order.
|
|
276
288
|
4. Take the sweep again after those publishes, because each release they add can leave another
|
|
277
289
|
package's development range trailing. Close the wave when a sweep lists no trailing range.
|
|
290
|
+
5. When `@orkestrel/scaffold`'s re-pin rules a bump, price the round first: that release leaves every
|
|
291
|
+
package's `@orkestrel/scaffold` range trailing, and `release.md` § The scaffold surface states what
|
|
292
|
+
each target owes. Bring the user the timing. While the release is held, commit the re-pin under a
|
|
293
|
+
subject that does not claim "no bump", state the owed release in its message, keep it unpushed,
|
|
294
|
+
and leave the wave open.
|