@orkestrel/scaffold 0.0.107 → 0.0.109

package/dist/host/agents/skills/orkestrel-publish/references/adopt.md

@@ -0,0 +1,23 @@
+# Adopt a published scaffold release in one consumer
+
+This file governs one consumer taking a published `@orkestrel/scaffold` release outside a release wave. [wave.md](wave.md) § Visit a repository owns the visit a wave runs; [release.md](release.md) § The scaffold surface owns what a vendored-only release obliges.
+
+Every verb and flag below is in `guides/scaffold.md` § Command line. `audit` writes nothing; `repair` writes each planned path the target is missing or has let drift, and reconciles the declared `@orkestrel/*` ranges and the script region on every run, whatever `--groups` names.
+
+## Steps
+
+1. **Restore pins.** Restore every tarball pin the consumer holds with `scripts/swap.ts --restore`, per [release.md](release.md) § Fix a dependency before it publishes, so the adoption reads registry ranges.
+2. **Re-pin.** Read the registry's `@orkestrel/scaffold` version, set the consumer's range to the caret of that release, and commit nothing yet.
+3. **Install against the registry.** Run `npm install` with `npm_config_prefer_online=true`, per [wave.md](wave.md) § Refresh the registry between layers. A cached packument answers `notarget` for a version the registry already serves.
+4. **Read the drift.** Run `scaffold audit` from the consumer, and add `--groups <list>` to scope it to the groups the consumer takes. Read its questions and findings before writing.
+5. **Repair.** Run `scaffold repair --groups <list>` over the groups the consumer takes, named per `guides/scaffold.md` § Groups. Omit `--offline`: it writes the distributed floors, not the registry's.
+6. **Restore held ranges.** `repair` rewrites the declared `@orkestrel/*` ranges and the showcase pair on every run (`guides/scaffold.md` § Dependency floors), so diff the manifest against `HEAD` and put back every range the consumer holds on purpose. The consumer's plan or ledger names each hold.
+7. **Reinstall.** Run the install of step 3 again; the restored manifest no longer matches the lockfile the first install wrote.
+8. **Run the gates.** Run the gate chain the consumer's manifest declares. `scaffold audit` exits `0` when the target matches its plan, `1` on drift, and `2` on a usage error. A drift a held range causes is expected; name it.
+9. **Rebuild committed artifacts.** Rebuild every artifact the consumer's plan names as committed (a generated registry, a snapshot, a mirror) with the consumer's own script, and read the diff.
+10. **Commit** by explicit paths, with the scaffold version in the message. A push to the remote waits for the user's go-ahead.
+
+## Refuse
+
+- Never run `repair` against the `@orkestrel/scaffold` checkout; the verb refuses it with the `TARGET` code.
+- Never edit a vendored file in the consumer to quiet `audit`; change it in the scaffold repository and release, per [release.md](release.md) § The scaffold surface.

package/dist/host/agents/skills/orkestrel-publish/references/release.md

@@ -1,11 +1,11 @@
 # Release laws
 
-`orkestrel-publish/SKILL.md` names this file. It carries the fleet release rules that bind an executor who is publishing or preparing a package to publish.
+The `orkestrel-publish` skill names this file. It carries the fleet release rules that bind an executor who is publishing or preparing a package to publish.
 
 ## Publishing is the user's
 
 - 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.
-- A publish chain is a long-running command: write it as a TypeScript file and launch it through the `orkestrel-dispatch` 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.
+- A publish chain is a long-running command: write it as a plan for the `orkestrel-dispatch` skill's `scripts/chain.ts` and launch the chain 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.
 - A wave over unpublished tips derives its order per run from the dependency graph and records only the round each package landed in.
 
 ## Fix a dependency before it publishes
@@ -29,8 +29,8 @@ When a consumer needs a dependency's unpublished source, to meet a defect that l
 - A runtime `dependencies` bump reaches every consumer: each package downstream re-pins, re-runs its gates, bumps, and republishes in layer order.
 - A development `devDependencies` bump reaches nobody: re-pin, prove the gates green, commit to `main`; do not bump or publish.
 - 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.
-- Every package is `0.0.x`, where a 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.
-- Read the order from the catalog table in `.claude/agents/orkestrel.md`, regenerated with `scaffold catalog` before sequencing a cascade. Never write a second order elsewhere.
+- 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.
+- Read each package's version and layer from the catalog table in `.claude/agents/orkestrel.md`, regenerated with `scaffold catalog` before sequencing a cascade. Never write a second order elsewhere.
 
 ## The scaffold surface
 

package/dist/host/agents/skills/orkestrel-publish/references/wave.md

@@ -23,10 +23,14 @@ overwrite receipts are written only where the work tree ignores `tmp/`.
    rewrite a peer range only when its name shares an audited release reading. For example, with
    peer-only `@orkestrel/peer-only: ^0.0.1`, leave that peer unchanged; with a planned tool whose
    registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though the tilde excludes `8.3.4`.
+   Keep a wave within each declared major. For a workspace whose selected framework activates a
+   `TOOLCHAIN_HOLDS` row, keep the tool within that range's major; read the audit question for its reason. Prove
+   that framework on the later major before lifting its hold.
 2. Commit the manifest and the lockfile as the preparation commit. `scaffold overwrite` refuses a
    tree carrying uncommitted changes, and the install left both dirty.
-3. Run `scaffold overwrite`. One run repairs the `AGENTS.md` and `CLAUDE.md` pointers and deletes
-   every tracked copy the target still holds at an instruction-canon path. Prove the sweep with a
+3. Run `scaffold overwrite`. One run repairs the `AGENTS.md` pointer and the skill pointer set and
+   deletes every tracked copy the target still holds at an instruction-canon path, a `CLAUDE.md`
+   included; the plan ships no `CLAUDE.md`. Prove the sweep with a
    second `scaffold audit` that exits `0`.
    - Where the target's `.claude/agents/orkestrel.md` carries a body outside the marker-bounded
      table that differs from the floor copy the installed scaffold stages, delete the file and
@@ -141,13 +145,12 @@ registry copy over any staged tip, so every consumer stays red until that tip is
 
 ## Prepare a layer
 
-- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor and move the package's CI floor row with it.
+- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor.
+- When a package still carries `.github/workflows/ci.yml`, delete it in that visit; the ecosystem runs no hosted CI.
 - Before the release, rule the package's guide and source comments against `.claude/rules/writing.md` § Substitutions and reword each hit its rows name; identifiers stay.
-- Compare release packs between hosts by paths, sizes, and content hashes, and report executable-mode differences separately; a pack made on Windows records `0644` for an entry git tracks as `100755`.
+- Compare release packs between hosts by paths, sizes, and content hashes, and report executable-mode differences separately (`.agents/platforms/windows.md` § Release packs and terminals).
 
-An unpublished package's first version is `0.0.1`. Do not bump it before that first publish. The
-registry has nothing to serve, so there is no version to move away from, and bumping produces a
-package whose history starts at a number nothing explains.
+An unpublished package's first version is `0.0.1`. Do not bump it before that first publish.
 
 Prepare a published package's layer in this order, after the visit has ruled the package's bump:
 
@@ -174,9 +177,8 @@ Prepare the next layer only after this one is on the registry. A dependent's new
 install until the version it names exists, so preparation and publication interleave and cannot be
 batched ahead.
 
-The window is for uploads. Every gate, build, install, and commit happens outside it, which is
-what makes `--ignore-scripts` the right flag at publish time: the artifact was already proved, and
-the flag is what stops the gate chain running a second time inside the five minutes.
+The window is for uploads. Every gate, build, install, and commit happens outside it; publish with
+`--ignore-scripts` so the gate chain does not run a second time on the proved artifact.
 
 ## Sweep the self-pins
 

package/dist/host/agents/skills/orkestrel-publish/references/window.md

@@ -13,16 +13,18 @@ rest of the layer either fits inside it or takes another approval.
 
 - Read the session with `node .agents/skills/orkestrel-publish/scripts/window.ts --whoami`; `--login` prints the command the operator runs in a real terminal and polls `whoami` until it answers. No child of a script holds the TTY npm needs, so the login itself is the operator's.
 
-- Run the login and every browser-authorized publish under `script -qfc '<command>' <log>`. npm
-  offers the browser approval only when it sees a TTY; without one it fails `EOTP` with no way to
-  answer. The one-time-code path runs under captured pipes instead, per § Authorize the upload.
+- Run the login and every browser-authorized publish in a real terminal: npm offers the browser
+  approval only when it sees a TTY, and without one it fails `EOTP` with no way to answer. A POSIX
+  Orchestrator gives npm one with `script -qfc '<command>' <log>`; on Windows the operator runs the
+  command (`.agents/platforms/windows.md` § Release packs and terminals). The one-time-code path
+  runs under captured pipes instead, per § Authorize the upload.
 - Pass `--browser=false` to `npm login` and to every `npm publish`. Without it npm prints
   `Press ENTER to open in the browser...` and blocks. Never answer that prompt with a newline: the
   web flow consumes the newline on a later read, drops to a legacy `Username:` prompt, and exits
   **zero** without authenticating. With the flag npm prints the URL and polls, and stdin stays
   untouched.
-- Hold stdin open and write nothing to it. Use a fifo held open by a long `sleep`. EOF drops npm
-  to the same legacy prompt a stray newline does.
+- Write nothing to npm's stdin and never close it: EOF drops npm to the same legacy prompt a
+  stray newline does.
 - Run `npm login` before any publish. The `npm publish` command does not open the browser flow:
   unauthenticated it returns `E404` on `PUT`, which reads as a missing package rather than as a
   missing credential.
@@ -33,14 +35,12 @@ rest of the layer either fits inside it or takes another approval.
 - Read a login log that shows the spinner and then a legacy `Username:` prompt as a dead attempt
   rather than as a prompt to answer: expired, or refused on its first poll per § Read a `403` on the
   poll. Kill it by the process id recorded at its launch, per the `orkestrel-dispatch` skill's launch
-  reference § Kill and relaunch. Every browser-authorized publish here runs under the same `script -qfc` form, so
-  a pattern over the process list reaches a live upload as readily as the dead login.
-- On a Windows host, Git Bash ships no `script` binary, so a browser-authorized upload is
+  reference § Kill and relaunch.
+- Where the Orchestrator has no TTY to give npm, a browser-authorized upload is
   operator-driven: prepare the layer, prove the gates, surface the exact `npm publish` command, and
   the operator runs it in a real terminal. Everything before and after the upload — bumps, re-pins,
   gates, registry reads — stays with the Orchestrator, and the one-time-code path in § Authorize the
-  upload runs through `window.ts` on every host. The fifo stdin law still binds a browser-authorized
-  upload on that host.
+  upload runs through `window.ts` on every host.
 
 ## Reach the approval
 
@@ -53,8 +53,7 @@ rest of the layer either fits inside it or takes another approval.
   prints `https://www.npmjs.com/auth/cli/<id>`.
 - Never shorten, redirect-strip, or otherwise improve a minted URL. The bare
   `https://www.npmjs.com/login/cli/<id>` target the login URL names is not a page: opened in a
-  browser it answers `{"message":"Unauthorized"}`. The user then reads a broken chain where the
-  chain is healthy, and the operator diagnoses the wrong failure.
+  browser it answers `{"message":"Unauthorized"}`.
 - Expect an unclicked session to die about 45 seconds after it is minted. Measured on 2026-08-27
   against `registry.npmjs.org` with `npm` 10.9.7 and `node` 22.22.2: npm polls `GET /-/v1/done`
   every few seconds and takes `202` while the session waits, and the registry answers `403` at
@@ -78,8 +77,7 @@ rest of the layer either fits inside it or takes another approval.
 - Read the URL out of the journal in the foreground and surface it before arming any watcher. A
   watcher-based relay can fail silently, and its silence is indistinguishable from a chain that
   has not reached the URL yet.
-- Relay the URL as plain text. A decorated link did not render for the operator, who then had
-  nothing to click while the window ran down.
+- Relay the URL as plain text; a decorated link did not render for the operator.
 - Re-read the log before treating an approval as failed. The chain is sometimes still alive on a
   later URL, so surface that one rather than starting the chain again.
 - Read a `404` on an approval URL as a publish that already succeeded and consumed it. Read the
@@ -92,9 +90,8 @@ rest of the layer either fits inside it or takes another approval.
 - Take the account's one-time code where the account has one. The
   `npm publish --ignore-scripts --otp=<code>` command uploads with no browser authorization and no
   poll. The code has its own life: measured on 2026-09-04 against `registry.npmjs.org`, one code
-  carried every upload of a layer started within about a minute of its first use, console at
-  20:25:02 through router at 20:25:58, and the upload started at 20:25:58 was refused `EOTP` at
-  20:26:00; a code read before its layer was ready was refused at its first upload.
+  carried every upload of a layer started within about a minute of its first use, and a code read
+  before its layer was ready was refused at its first upload.
 - Prepare the whole layer, then ask for one code at the moment the layer's first upload starts, and
   chase the layer's uploads back-to-back inside that code's life with no gate between them. A code
   read minutes earlier is already spent.
@@ -103,12 +100,11 @@ rest of the layer either fits inside it or takes another approval.
   from that package on a fresh code. Never retry the refused upload on the same code.
 - Ask for the code and nothing else. Never ask for a password, an access token, or an auth file.
   `release.md` § Publishing is the user's owns that law.
-- A one-time-code upload needs no terminal arming: `window.ts --publish` holds the upload under
-  captured pipes, where npm's non-TTY guard rethrows an authentication refusal instead of prompting,
-  so a spent code is refused `EOTP` with no prompt and no browser flow, which is the stop the runner
-  reads. The runner passes `--browser=false` and re-reads `whoami` immediately before the first
-  upload. Never run a one-time-code upload on a TTY: there npm answers a refused code with a prompt
-  the chain cannot see.
+- A one-time-code upload needs no terminal arming: `window.ts --publish` runs it under captured
+  pipes, where a spent code is refused `EOTP` with no prompt and no browser flow, which is the stop
+  the runner reads. The runner passes `--browser=false` and re-reads `whoami` immediately before the
+  first upload. Never run a one-time-code upload on a TTY: there npm answers a refused code with a
+  prompt the chain cannot see.
 - Fall back to the browser authorization where the account answers with no code. That path mints
   the `auth/cli/<id>` URL, needs the click inside the session's life, and opens the five-minute
   window.
@@ -184,5 +180,4 @@ the same status. Rule from the evidence, never from which cause reads likelier.
 - Rule on a pack-time manifest-rewriting warning by fetching the registry's copy of the manifest,
   never by the warning's own text.
 - Re-read the registry before telling the user a package failed. A chain still running, a retry
-  that landed, and CDN lag all produce a failure reading that the registry contradicts, and a
-  false failure report costs a needless approval and a needless republish.
+  that landed, and CDN lag all produce a failure reading that the registry contradicts.