@orkestrel/scaffold 0.0.26 → 0.0.28

package/dist/host/agents/orchestration.md

@@ -1,6 +1,7 @@
 # Orchestration
 
-How agents are dispatched, supervised, and accepted. Every harness follows this file.
+How agents are dispatched, how long-running work is supervised, and how both are accepted. Every
+harness follows this file.
 
 ## Authority
 
@@ -216,6 +217,13 @@ clobbered edits, formatter and build races, cache phantoms, and validation cross
    sharing one working tree contaminate each other's readings in both directions.
 6. After integration, clear shared caches if needed, then have one independent `verifier` run the
    authoritative tree-wide sweep. A writer's self-report never establishes green.
+7. The Orchestrator's own sweep is a writing dispatch and queues behind the units that own those
+   files. A script that fixes one thing across every target is the easiest way to break rule 1,
+   because it does not feel like a dispatch — nobody was named, no brief was written, and it
+   finishes in seconds. It still writes into trees a live unit owns, and a unit whose brief it
+   invalidates will repair the same drift the other way and report a state that is already false.
+   Run it before the units, or after them, or send the decision to every unit in flight per the
+   mid-campaign rule under **Dispatch anatomy**. Never beside them.
 
 ## Execution loop
 
@@ -347,6 +355,24 @@ The harness bridge names the concrete mechanism for each of these.
 - Promote anything that must outlive the campaign into a durable artifact before the sweep — a
   commit message, a guide, a rule, a retrospective. What is only in a swept file did not survive.
 
+### Where campaign artifacts live
+
+- Put every campaign artifact in the **orchestrator's** repository under `.orkestrel/<package>/`,
+  named for the package the campaign is about.
+- Never put them in the package they are about. A published package's tree is its product.
+- Claim nothing outside `.orkestrel/` unless Orkestrel scaffold mandates it. Everything Orkestrel
+  owns in a consumer's tree lives beneath that folder, so a convention can be settled there without
+  colliding with a convention that is not Orkestrel's.
+- Keep the campaign narrative and every ruling in the durable artifact that owns it — the guide for
+  product truth, a rule or role file for process truth, the commit message for the decision itself.
+  Use `ROADMAP.md` only where the repository already keeps one.
+- Prefer a mechanism that recomputes a fact over a document that records it. A ledger of live state
+  is stale from the moment it is written, and the next campaign reads it as current. Where the fact
+  can be derived, derive it: the fleet's publish order lives in the catalog table `scaffold catalog`
+  regenerates, not in a written order anyone has to remember to update.
+- Prune the campaign folder in a commit at acceptance. The tree ends clean and the record stays
+  recoverable by hash. Git history is the archive; the working tree is the workspace.
+
 ### Required sections
 
 - **Role and engine.** The named role and its explicit engine.
@@ -416,6 +442,70 @@ wrong is right to stop.
 After reconciling findings into briefs, walk the retained finding list once. Every finding names
 the brief item that carries it. A finding with no carrier is a dropped finding.
 
+## Long-running commands
+
+A bench exec, a Workflow, an install, a build, and a publish chain are one class of thing: a
+command that outlives the turn that started it. Every law here binds all of them.
+
+### Launching
+
+- The Orchestrator launches every long command as a harness-tracked background command under a hard
+  time cap. Never detach one from inside a dispatched agent. The harness owns the lifecycle,
+  completion re-invokes the session, and the cap kills a wedged command loudly instead of trusting
+  the agent to report its own failure. A wedged bridge is silent, and silence must never read as
+  progress.
+- Write a multi-step chain to a script file and run the file. A chain composed inside one shell
+  argument cannot be read back, corrected, or re-run, and the record of what actually ran is the
+  argument text in a transcript rather than a file on disk.
+- Detach anything that must survive its launching shell with `setsid`. A backgrounded flow the
+  harness reaps mid-step leaves the work half done and the exit status missing, and the reap looks
+  identical to the step failing.
+- Size the cap from the observed high mark of comparable commands, plus an independently budgeted
+  gate allowance, plus explicit slack. Never size it from the estimate alone.
+- Run the first use of any CLI flag, subcommand, quoting form, or stdin combination in a throwaway
+  probe. Never inside a dispatched unit or a publish chain.
+- A launch is not a launch until its record grows past its header. Confirm the log advanced beyond
+  the head before recording that the command started, and treat an instantly-dead log as a failed
+  launch whose tail is the evidence.
+- Keep network-dependent work out of sandboxed bench execs. Bench sandboxes deny network, so
+  lockfile generation, real installs, and live fetches belong to the Orchestrator's own tracked
+  commands or a network-capable native agent. A bench exec hanging on `npm` until its cap fires is
+  the signature of this misroute, not of a slow bench.
+- A Workflow journals identically and dies identically, so give it the same watch — with one
+  correction. A workflow journal writes only at agent start and result, so its mtime goes quiet for
+  minutes during healthy work, and the liveness signal is the newest subagent transcript instead. A
+  watch that reports only new events cannot report a death, because silence and progress look the
+  same; the filter must fire on absence. Recover with `resumeFromRunId`, which returns every
+  completed agent from cache and re-runs only what never finished.
+
+### Reading liveness
+
+Read liveness from the artifact the work produces, never from its wrapper. A subagent's transcript
+file can report zero bytes while the agent is working normally, so an empty or stale wrapper proves
+nothing.
+
+- Judge a unit by what it has changed in the tree: modification times on the files it owns, the
+  counts its suite reports, the report it was told to write.
+- Check that before killing anything. A healthy unit killed on a false signal loses everything it
+  had not yet written down, and the loss is charged to the orchestrator, not the unit.
+- If a unit must be stopped, say plainly that it was stopped and why, then assess the tree it left
+  rather than assuming its partial bytes are either good or worthless.
+- Follow the deviation ladder for a stalled journal or a cap-killed exec, using the session id from
+  the journal head as the recovery handle.
+
+### Confirm dead before relaunching
+
+- Prove the previous run is gone before starting another. List the processes and read the list. A
+  second run started beside a live first one produces failures that read as the subject's — a
+  publish chain relaunched over a live one reports `EOTP` and `E403` that are its own two processes
+  colliding, and both readings point at the registry.
+- Kill by process id, never by pattern. `pkill -f` matches the relaunch that is already starting, so
+  the pattern that cleans up the old run kills the new one and the cleanup reads as a launch
+  failure.
+- Read a failure against what was running when it happened, not against what you believe was
+  running. The check costs one command and is the only thing that separates a real failure from
+  self-inflicted contention.
+
 ## Bench laws
 
 External engines widen capacity. They never inherit authority. Treat every bench output as a
@@ -424,6 +514,9 @@ proposal or hypothesis until it is verified against source and accepted by the O
 A bench is cross-provider reach only. Never send a model across a bridge when the running harness
 hosts it natively.
 
+A bench exec is a long-running command, so every law under **Long-running commands** binds it too.
+This section adds what is true of a bench and nothing else.
+
 Every bridge verifies before running that its CLI resolves and its bench is authenticated, and stops
 with a deviation report naming the fallback when either fails. The role file owns the exact
 invocation, flags, paths, probe, and recovery ladder; these four laws bind every bench regardless of
@@ -452,45 +545,6 @@ transport.
    is dispatched and as it returns, because each encodes knowledge that costs real money to
    re-derive and none of it is reproducible from the diff.
 
-### Where campaign artifacts live
-
-- Put every campaign artifact in the **orchestrator's** repository under `.orkestrel/<package>/`,
-  named for the package the campaign is about.
-- Never put them in the package they are about. A published package's tree is its product.
-- Claim nothing outside `.orkestrel/` unless Orkestrel scaffold mandates it. Everything Orkestrel
-  owns in a consumer's tree lives beneath that folder, so a convention can be settled there without
-  colliding with a convention that is not Orkestrel's.
-- Keep the campaign narrative and every ruling in the durable artifact that owns it — the guide for
-  product truth, a rule or role file for process truth, the commit message for the decision itself.
-  Use `ROADMAP.md` only where the repository already keeps one.
-- Prune the campaign folder in a commit at acceptance. The tree ends clean and the record stays
-  recoverable by hash. Git history is the archive; the working tree is the workspace.
-
-### Launching a long exec
-
-- The Orchestrator launches every long bench exec as a harness-tracked background command under a
-  hard time cap. Never detach one from inside a bridge agent. The harness owns the lifecycle,
-  completion re-invokes the session, and the cap kills a wedged bench loudly instead of trusting
-  the bridge to report its own failure. A wedged bridge is silent, and silence must never read as
-  progress.
-- A Workflow journals identically and dies identically, so give it the same watch — with one
-  correction. A workflow journal writes only at agent start and result, so its mtime goes quiet for
-  minutes during healthy work, and the liveness signal is the newest subagent transcript instead. A
-  watch that reports only new events cannot report a death, because silence and progress look the
-  same; the filter must fire on absence. Recover with `resumeFromRunId`, which returns every
-  completed agent from cache and re-runs only what never finished.
-- Size the cap from the observed high mark of comparable units, plus an independently budgeted gate
-  allowance, plus explicit slack. Never size it from the estimate alone.
-- Run the first use of any CLI flag, subcommand, quoting form, or stdin combination in a throwaway
-  probe. Never inside a dispatched unit.
-- A launch is not a launch until the journal grows past its header. Confirm the event stream
-  advanced beyond the session-configured head before recording that the exec started, and treat an
-  instantly-dead journal as a failed launch whose tail is the evidence.
-- Keep network-dependent work out of sandboxed bench execs. Bench sandboxes deny network, so
-  lockfile generation, real installs, and live fetches belong to the Orchestrator's own tracked
-  commands or a network-capable native agent. A bench exec hanging on `npm` until its cap fires is
-  the signature of this misroute, not of a slow bench.
-
 ### Recovering a dark bench
 
 - A probe that finds a bench binary present but authentication unavailable starts recovery in the
@@ -503,20 +557,95 @@ transport.
   cannot complete, record the bench dark, name the fallback in the plan, and say so.
 - The role file owns each bench's exact login command and probe.
 
-### Reading liveness
-
-Read liveness from the artifact the work produces, never from its wrapper. A subagent's transcript
-file can report zero bytes while the agent is working normally, so an empty or stale wrapper proves
-nothing.
-
-- Judge a unit by what it has changed in the tree: modification times on the files it owns, the
-  counts its suite reports, the report it was told to write.
-- Check that before killing anything. A healthy unit killed on a false signal loses everything it
-  had not yet written down, and the loss is charged to the orchestrator, not the unit.
-- If a unit must be stopped, say plainly that it was stopped and why, then assess the tree it left
-  rather than assuming its partial bytes are either good or worthless.
-- Follow the deviation ladder for a stalled journal or a cap-killed exec, using the session id from
-  the journal head as the recovery handle.
+## Publishing the fleet
+
+Publishing is the user's decision and the user's credential. The Orchestrator prepares, surfaces
+the approval, and runs the publishes the user asked for. It never substitutes an API key, an access
+token, a copied auth file, or another login flow, and it never asks the user to paste a token into
+the conversation.
+
+A publish chain is a long-running command, so every law under **Long-running commands** binds it:
+write the chain to a file, detach it with `setsid`, and confirm the previous one is dead before
+starting another.
+
+### What a bump obliges
+
+A runtime dependency and a development dependency have different blast radius, and confusing them
+either publishes packages nobody needed to publish or leaves a consumer pinned to an older release.
+
+- A **runtime** `dependencies` bump reaches every consumer of the published package. Every package
+  downstream of it re-pins, re-runs its gates, bumps, and republishes, in layer order.
+- A **development** `devDependencies` bump reaches nobody. Re-pin it, prove the gates still green,
+  and commit to `main`. Do not bump the version and do not publish.
+- A development bump that forces a change to `src` or `app` is no longer a development bump. The
+  published types or runtime moved, so that package bumps and publishes on its own account, and
+  its own dependents follow the runtime rule above.
+
+Every package is `0.0.x`, where a caret pins one exact release. A dependent therefore sees a new
+version only after it re-pins and republishes, so the fleet publishes in topological layer order
+derived from runtime `dependencies` alone. Layers exist for a reason a flat pass cannot fix: two
+ranges that disagree install two copies of the same package, and the compiler reads them as two
+distinct types.
+
+Read the order from the catalog table in `.claude/agents/orkestrel.md`, which `scaffold catalog`
+regenerates from the registry. Its `Layer` column is the publish round. Regenerate it before
+sequencing a cascade rather than trusting the copy in the tree, and never write a second order down
+somewhere else.
+
+The tooling packages sit outside that order because nothing depends on them at runtime. `scaffold`
+is a development dependency of every package, including packages it depends on itself, so a runtime
+layering would report a cycle that does not exist. Each package builds against the already-published
+`scaffold`, never against an unpublished one, and a `scaffold` release therefore publishes on its own
+and propagates as files rather than as a cascade.
+
+### Preparing
+
+1. **Bump from what the registry serves, not from the local manifest.** A repository's `version`
+   can sit a release behind what was published from another checkout, and bumping that produces a
+   version the registry already holds, which fails on upload after the whole gate chain has run.
+   Read the registry first.
+2. **Prepare a whole layer before authenticating.** Bump each version, re-pin every `@orkestrel`
+   range to what the registry serves now, install, and run the package's own `prepublishOnly` to
+   green. Move any self-pin in source with the manifest. Commit and push before the window opens.
+3. **Prepare the next layer only after this one is on the registry.** A dependent's new pin cannot
+   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.
+
+### Reaching the approval
+
+- **Log in first** when the session is new or a day has passed. `npm login` and `npm publish` reach
+  the same browser approval, and a publish that has to run the login flow spends the window on it.
+- `npm login` backgrounded with stdin at EOF falls through to a legacy `Username:` prompt and exits
+  **zero** without authenticating. Confirm with `npm whoami` rather than an exit code.
+- npm offers its browser approval only when it sees a TTY. Without one it fails `EOTP` and there is
+  no way to answer it. Run the login, and the first publish of a layer, under
+  `script -qfc '<command>' <log>` with stdin read from a fifo a long `sleep` holds open.
+- npm prints `Press ENTER to open in the browser` and does not begin polling until that is
+  acknowledged. Send a newline into the fifo. The browser it tries to open does not exist in a
+  headless container, which is harmless.
+- Surface the approval URL to the user the moment it appears in the log, and say that approving it
+  opens a five-minute window covering the rest of the layer.
+
+### Spending the window
+
+- The window opens when the user approves, not when the first publish starts. Chain every remaining
+  publish inside the same process as the gate package, so no human turn sits inside it.
+- Publish serially. Concurrent publishes collide on the auth handshake and fail each other.
+- `EOTP` inside the window is intermittent contention rather than the window closing. Retry each
+  package about three times before recording it failed, and retry a failed set once the layer ends;
+  packages have landed on the third attempt and on a later pass with no new approval.
+- Expect a large layer to outlast one window. Size batches to what uploads in five minutes and tell
+  the user how many approvals to expect, rather than discovering it mid-run.
+- Read the result from the registry, not from an exit code: a piped `npm publish` reports the exit
+  status of the pipeline, and a CDN read straight after a publish can still serve the previous
+  version.
+- 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.
 
 ## Acceptance laws
 

package/dist/host/claude/agents/orkestrel.md

@@ -34,49 +34,49 @@ so network-controlled descriptions never enter agent instruction context.
 
 <!-- orkestrel:catalog -->
 
-| Package                 | Version  |
-| ----------------------- | -------- |
-| `@orkestrel/abort`      | `0.0.5`  |
-| `@orkestrel/agent`      | `0.0.14` |
-| `@orkestrel/browser`    | `0.0.8`  |
-| `@orkestrel/budget`     | `0.0.5`  |
-| `@orkestrel/console`    | `0.0.4`  |
-| `@orkestrel/contract`   | `0.0.10` |
-| `@orkestrel/csv`        | `0.0.2`  |
-| `@orkestrel/database`   | `0.0.7`  |
-| `@orkestrel/emitter`    | `0.0.5`  |
-| `@orkestrel/guide`      | `0.0.9`  |
-| `@orkestrel/html`       | `0.0.2`  |
-| `@orkestrel/indexeddb`  | `0.0.6`  |
-| `@orkestrel/interpret`  | `0.0.7`  |
-| `@orkestrel/markdown`   | `0.0.7`  |
-| `@orkestrel/mcp`        | `0.0.13` |
-| `@orkestrel/middleware` | `0.0.9`  |
-| `@orkestrel/msg`        | `0.0.5`  |
-| `@orkestrel/ndjson`     | `0.0.5`  |
-| `@orkestrel/ollama`     | `0.0.8`  |
-| `@orkestrel/pool`       | `0.0.6`  |
-| `@orkestrel/program`    | `0.0.6`  |
-| `@orkestrel/qualifier`  | `0.0.7`  |
-| `@orkestrel/queue`      | `0.0.7`  |
-| `@orkestrel/rater`      | `0.0.8`  |
-| `@orkestrel/reason`     | `0.0.4`  |
-| `@orkestrel/relation`   | `0.0.7`  |
-| `@orkestrel/router`     | `0.0.8`  |
-| `@orkestrel/scaffold`   | `0.0.24` |
-| `@orkestrel/sea`        | `0.0.5`  |
-| `@orkestrel/server`     | `0.0.10` |
-| `@orkestrel/sqlite`     | `0.0.6`  |
-| `@orkestrel/sse`        | `0.0.4`  |
-| `@orkestrel/template`   | `0.0.2`  |
-| `@orkestrel/terminal`   | `0.0.5`  |
-| `@orkestrel/timeout`    | `0.0.5`  |
-| `@orkestrel/tool`       | `0.0.9`  |
-| `@orkestrel/toolbox`    | `0.0.3`  |
-| `@orkestrel/websocket`  | `0.0.7`  |
-| `@orkestrel/worker`     | `0.0.6`  |
-| `@orkestrel/workflow`   | `0.0.10` |
-| `@orkestrel/workspace`  | `0.0.3`  |
+| Package                 | Version  | Layer | Runtime dependencies                                                                                                                                                                                                                                                                                                 |
+| ----------------------- | -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@orkestrel/abort`      | `0.0.6`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/agent`      | `0.0.15` | L5    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/budget` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/queue` `^0.0.8`, `@orkestrel/timeout` `^0.0.6`, `@orkestrel/tool` `^0.0.10`, `@orkestrel/workflow` `^0.0.11`, `@orkestrel/workspace` `^0.0.4` |
+| `@orkestrel/browser`    | `0.0.9`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/html` `^0.0.3`, `@orkestrel/websocket` `^0.0.8`                                                                                                                                                                                          |
+| `@orkestrel/budget`     | `0.0.6`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/console`    | `0.0.5`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                       |
+| `@orkestrel/contract`   | `0.0.11` | L0    |                                                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/csv`        | `0.0.3`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/database`   | `0.0.8`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/indexeddb` `^0.0.7`, `@orkestrel/sqlite` `^0.0.7`                                                                                                                                                                                        |
+| `@orkestrel/emitter`    | `0.0.6`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/guide`      | `0.0.10` | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/markdown` `^0.0.8`                                                                                                                                                                                                                                                      |
+| `@orkestrel/html`       | `0.0.3`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/indexeddb`  | `0.0.7`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/interpret`  | `0.0.8`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/reason` `^0.0.5`, `@orkestrel/template` `^0.0.3`                                                                                                                                                                                         |
+| `@orkestrel/markdown`   | `0.0.8`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/html` `^0.0.3`                                                                                                                                                                                                                                                          |
+| `@orkestrel/mcp`        | `0.0.14` | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/sse` `^0.0.5`, `@orkestrel/tool` `^0.0.10`, `@orkestrel/websocket` `^0.0.8`                                                                                                                                                              |
+| `@orkestrel/middleware` | `0.0.10` | L2    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/budget` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/timeout` `^0.0.6`                                                                                                                                                                                            |
+| `@orkestrel/msg`        | `0.0.6`  | L0    |                                                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/ndjson`     | `0.0.6`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/ollama`     | `0.0.9`  | L6    | `@orkestrel/agent` `^0.0.15`, `@orkestrel/budget` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/ndjson` `^0.0.6`, `@orkestrel/timeout` `^0.0.6`, `@orkestrel/tool` `^0.0.10`                                                                                                                                |
+| `@orkestrel/pool`       | `0.0.7`  | L2    | `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                                                        |
+| `@orkestrel/program`    | `0.0.7`  | L4    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/qualifier` `^0.0.8`, `@orkestrel/rater` `^0.0.9`, `@orkestrel/reason` `^0.0.5`                                                                                                                                                           |
+| `@orkestrel/qualifier`  | `0.0.8`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/reason` `^0.0.5`                                                                                                                                                                                                                         |
+| `@orkestrel/queue`      | `0.0.8`  | L3    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/timeout` `^0.0.6`                                                                                                                                                           |
+| `@orkestrel/rater`      | `0.0.9`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/reason` `^0.0.5`                                                                                                                                                                                                                         |
+| `@orkestrel/reason`     | `0.0.5`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                       |
+| `@orkestrel/relation`   | `0.0.8`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                       |
+| `@orkestrel/router`     | `0.0.9`  | L2    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                          |
+| `@orkestrel/scaffold`   | `0.0.27` | L3    | `@orkestrel/console` `^0.0.5`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/markdown` `^0.0.8`, `@orkestrel/template` `^0.0.3`                                                                                                                                                        |
+| `@orkestrel/sea`        | `0.0.6`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                       |
+| `@orkestrel/server`     | `0.0.11` | L3    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/router` `^0.0.9`, `@orkestrel/timeout` `^0.0.6`                                                                                                                                                             |
+| `@orkestrel/sqlite`     | `0.0.7`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/sse`        | `0.0.5`  | L0    |                                                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/template`   | `0.0.3`  | L2    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                       |
+| `@orkestrel/terminal`   | `0.0.6`  | L3    | `@orkestrel/console` `^0.0.5`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/sse` `^0.0.5`                                                                                                                                                             |
+| `@orkestrel/timeout`    | `0.0.6`  | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/tool`       | `0.0.10` | L1    | `@orkestrel/contract` `^0.0.11`                                                                                                                                                                                                                                                                                      |
+| `@orkestrel/toolbox`    | `0.0.4`  | L6    | `@orkestrel/agent` `^0.0.15`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/relation` `^0.0.8`, `@orkestrel/server` `^0.0.11`, `@orkestrel/terminal` `^0.0.6`, `@orkestrel/tool` `^0.0.10`, `@orkestrel/workflow` `^0.0.11`, `@orkestrel/workspace` `^0.0.4`                          |
+| `@orkestrel/websocket`  | `0.0.8`  | L2    | `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                                                                                        |
+| `@orkestrel/worker`     | `0.0.7`  | L4    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/pool` `^0.0.7`, `@orkestrel/queue` `^0.0.8`                                                                                                                                                              |
+| `@orkestrel/workflow`   | `0.0.11` | L4    | `@orkestrel/abort` `^0.0.6`, `@orkestrel/budget` `^0.0.6`, `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`, `@orkestrel/queue` `^0.0.8`, `@orkestrel/timeout` `^0.0.6`                                                                                                |
+| `@orkestrel/workspace`  | `0.0.4`  | L3    | `@orkestrel/contract` `^0.0.11`, `@orkestrel/database` `^0.0.8`, `@orkestrel/emitter` `^0.0.6`                                                                                                                                                                                                                       |
 
 <!-- /orkestrel:catalog -->
 
@@ -89,11 +89,28 @@ range as a pin, never as a range. A dependent stays on its pinned version until
 rewrites the dependent's own declared range and re-publishes the dependent. Publishing a
 new version reaches no consumer on its own.
 
-A bump therefore obliges a re-publish of every package downstream of it, in dependency
-order. Report that cascade whenever you sequence cross-package work or state blast
-radius: name each downstream package, its declared range, and its position in the order.
-A package whose pin names an older version runs that older version, whatever the registry
-holds.
+A **runtime** bump therefore obliges a re-publish of every package downstream of it, in
+layer order. Report that cascade whenever you sequence cross-package work or state blast
+radius: name each downstream package, its declared range, and its layer. A package whose
+pin names an older version runs that older version, whatever the registry holds.
+
+A **development** bump obliges nothing. A `devDependencies` range reaches no consumer of
+the published package, so re-pin it, prove the gates still green, and stop. Never report a
+development bump as a cascade. It becomes one only if it forces a change to `src` or
+`app`, because then the published types or runtime moved and the package bumps on that
+account rather than on the dependency's.
+
+The `Layer` column above is the publish round, derived from the runtime edges in the same
+row. `L0` depends on nothing else in the fleet and publishes first; each later layer
+publishes only after every layer before it is on the registry. A row with no layer sits in
+a cycle and cannot be placed in a round at all. Two packages in one layer are independent
+of each other and may publish in any order within it.
+
+Report a disagreeing pin as a defect, never as drift to tidy later. When two packages in
+one install graph pin different versions of a third, npm installs both copies, and the
+compiler reads the two copies as two distinct types. The symptom is a type error naming
+one type as not assignable to itself. `npm ls @orkestrel/<name>` is the evidence: one line
+is sound, and nesting is the finding.
 
 ## Evidence workflow
 

package/dist/host/claude/agents/researcher.md

@@ -4,6 +4,7 @@ description: 'Read-only primary-source research: external capabilities, protocol
 tools: Read, Grep, Glob, WebFetch, WebSearch
 model: sonnet
 effort: medium
+permissionMode: dontAsk
 ---
 
 You are the **Researcher** — the native evidence lane for the research job the

package/dist/host/claude/agents/scout.md

@@ -4,6 +4,7 @@ description: 'Read-only repository reconnaissance: locate files, symbols, seams,
 tools: Read, Grep, Glob
 model: sonnet
 effort: low
+permissionMode: dontAsk
 ---
 
 You are the **Scout** — the cheap native reconnaissance lane in this project's

package/dist/host/claude/rules/architecture.md

@@ -67,6 +67,25 @@ Use only the centralized files an environment needs.
   creates a directory rather than an entity and `isVacant` is a predicate rather than a `Guard<T>`,
   so both stay in `helpers.ts`. Placement follows what the function is; the name form follows
   placement.
+- Repair a violation of those forms by deciding what the function **is** first, then moving or
+  renaming to match. Both repairs exist and picking the wrong one does real damage.
+  - Wrong file, right name → **move it**. A `scan*` in `parsers.ts` is a pure lexical leaf that
+    belongs in `helpers.ts`. The barrel star-exports both, so the move leaves the published surface
+    identical.
+  - Right file, wrong name → **rename it in place**. A function returning a live entity is an entity
+    factory and belongs in `factories.ts` whatever it is called, so `restoreThing` there is misnamed,
+    not misplaced. Renaming moves the published surface and earns a version bump; that cost is the
+    correct one to pay, and it is smaller than the alternative.
+  - Never let the name choose. Relocating a correctly-placed function to escape a rename drags its
+    dependencies with it — an entity factory moved into `helpers.ts` makes that file import an
+    implementation class, and a leaf file that imports a class stops being a leaf for every module
+    beneath it.
+- Keep the leaf pair class-free. `helpers.ts` and `validators.ts` sit at the bottom of a module's
+  graph: they import types, constants, errors, and each other, and they import no implementation
+  class. Every file that constructs or drives a class — `cloners.ts`, `compilers.ts`, `factories.ts`,
+  `shapers.ts` — sits above them, consumes them, and is never consumed by them. One cycle between
+  the two leaves is the shape this produces and is acceptable; an edge running downward from a
+  class-importing file into the leaf pair is not.
 - `templates.ts` and `contracts.ts` hold data only — shipped template definitions and compiled
   contracts. A function that builds either belongs in the kind file for what it builds.
 - `handlers.ts` holds request handlers, which are functions. `routes.ts` holds data only: a route is

package/dist/host/claude/rules/documentation.md

@@ -32,6 +32,8 @@ Documentation is an enforced contract, not explanatory decoration. The Writing r
 - Every public export is documented.
 - TypeScript, SCSS, Markdown, tests, and showcase remain aligned.
 - A parity failure identifies drift; never suppress or weaken the test.
+- Falsify a prose claim the way you falsify a code claim. The parity test proves a name exists, never that a sentence about behavior is true, so run the example and read what it returns. A `// false` beside a call that returns `true` is a defect of the same kind as a wrong return value, and it reaches every consumer who installs the package.
+- Re-read the prose last, against what actually shipped. Where a change chose to document a limit rather than close it, the sentence was often drafted for the option that lost, or written more confidently than the code earns. Code rulings survive review because a test can break them; prose rulings survive because nothing tries.
 
 For behavioral interfaces/classes:
 

package/dist/host/claude/rules/quality.md

@@ -63,9 +63,12 @@ A review that reads a diff finds what the diff shows. A review that tries to bre
 - Draw the negative control from outside the population the instrument covers. Name the instrument's membership rule first, then pick a control that rule excludes. A control sampled from constructs the instrument already handles proves only that it discriminates among those constructs, and says nothing about the class it silently cannot reach.
 - State an instrument's coverage beside its result. A conclusion inherits the instrument's scope, not the question's. An unstated coverage claim is read as complete, and it never is. A search proves something about the paths it walked, so name them.
 - Match the instrument to the question. A text search reports on text, so a claim about declarations, call sites, or structure needs the compiler or a parser instead. A pattern written for one spelling of a construct reports on that spelling alone. A path check answers relative to the directory it runs from, so resolve the inputs against their own base before reading a miss as a finding.
+- Report a question unanswered rather than answering it with a weaker instrument. A fallback that measures something adjacent returns a confident wrong answer, and nothing downstream can tell that answer from the real one — searching commit messages for a release when the question is where a version changed will match some release, just not the one asked about. Name the substitute and what it actually measures, or say the question is open.
 - State what the controls established and what they did not. An instrument certified only from the inside is trusted exactly where it has never been tested.
 - Treat a gap between what an instrument says it checks and what it actually matches as a defect in the instrument, not as a documented limit. A recorded blind spot buys trust only when everything outside it is genuinely covered.
 - Measure the product, not the harness. A recorded baseline that counts something about its own fixture is not evidence about the shipped surface, however often a guide quotes it.
+- Baseline a published-artifact claim against the published artifact. "Did my change move the surface" and "does this release differ from the last one" are different questions, and a diff against your own starting point answers only the first. A toolchain that re-emits declarations moves the artifact without any source edit, so every writer can correctly report an unmoved surface while the package's published contract has changed. Fetch what consumers actually have — the tarball, the deployed asset — and compare against that.
+- Prove a module cycle by loading the built artifact, not by a green suite. Tests import through the source graph and a bundler resolves it differently, so a cycle that is fatal at module-init in the shipped form can stay invisible under every test. Import each published entry point and read an export from it.
 - Adopt an instrument that settled a claim as a test before accepting the work it settled. The probe that proved a fix, carrying the control that proved the probe, is that fix's regression guard. A verification that runs once is a rehearsal, not a gate.
 
 ### Rounds and verdicts

package/dist/host/claude/rules/tests.md

@@ -22,6 +22,10 @@ paths:
 - Cover happy paths, error paths, empty input, boundary values, `NaN`, positive/negative zero, cycles, and Map/Set order where relevant.
 - Test observable behavior, not implementation details.
 - Assert the membership a discovered or globbed set should have, not a total that a partly empty population satisfies. A glob spanning two locations passes a size check while one of them matches nothing.
+- Never assert an implementation against itself. Compare the answer to a declaration, a fixture, or a second mechanism that could disagree with it. Re-deriving the answer the same way the source derives it produces a test that passes for every value the source ever returns, and it reads exactly like a real one.
+- Probe a host-varying property at runtime, on the host the test is running on, and assert against what the probe returned. Filesystem case folding, path separators, permission bits, and rename semantics differ per host, so a fixture built on one host describes that host and silently measures something else on the next.
+- Assert a runtime-chosen result as the property it must have, not as the number one run produced. Compression, timing, and buffer sizing are the runtime's choice, so pin the relationship the test depends on — that the encoded form is larger, that the second call is faster — and let the assertion fail when the input drifts out of the range where that relationship holds.
+- Give a conditional skip the mechanism that makes it inapplicable, cited, not the platform name alone. A test skipped on a platform is a test nobody re-examines; a test skipped because a named API rejects a named case is one anybody can re-check.
 - A regression test records the exact command and its failing count before the fix, and the same command's passing count after.
 - Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every `.skip` or conditional skip has a narrow verifiable applicability reason.
 - Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
@@ -32,12 +36,14 @@ paths:
 A proof that covers the workspace instead of one module has a fixed location, so no package invents
 its own:
 
-| Path                        | Proves                                                         |
-| --------------------------- | -------------------------------------------------------------- |
-| `tests/policy.test.ts`      | Every source file obeys the syntactic coding and placement law |
-| `tests/config.test.ts`      | Root configuration resolves its aliases, projects, and outputs |
-| `tests/guides.test.ts`      | Every documented API exists and every public API is documented |
-| `tests/integration.test.ts` | The built package works when installed and driven from outside |
+| Path                         | Proves                                                          |
+| ---------------------------- | --------------------------------------------------------------- |
+| `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law  |
+| `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs  |
+| `tests/guides.test.ts`       | Every documented API exists and every public API is documented  |
+| `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks   |
+| `tests/integration.test.ts`  | The built package works when installed and driven from outside  |
+| `tests/service/**/*.test.ts` | The live external services this package drives, driven for real |
 
 - `.claude/rules/workspace.md` names the Vitest project each location belongs to.
 - `integration.test.ts` is a reserved filename at any level. It names a scope rather than a module,
@@ -76,9 +82,11 @@ Three rules bind every probe:
 
 Live external services/models are the deliberate exception to fast hermetic defaults:
 
-- Put them in a dedicated isolated Vitest project with its own setup and longer timeout.
+- Put them in the `service` project, under `tests/service/`, with `tests/setupService.ts` for setup
+  and a longer timeout. That module's presence is what registers the project, so a live proof with
+  no readiness setup is a project nothing configures.
 - Keep them out of the default run.
-- Warm and verify service readiness in setup.
+- Warm and verify service readiness in `tests/setupService.ts`.
 - Hard-require readiness: throw loudly; never silently skip.
 - Verify service-dependent logic through that service's project, not unrelated module tests or scattered conditional skips.
 - Tune each request to the smallest input/context/output that proves one behavior without becoming brittle or expensive.
@@ -91,6 +99,7 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
 - Give it its own Vitest project with its own setup and timeout.
 - Keep it out of the default run and require it in `prepublishOnly`.
 - Slow and hermetic is reason enough to isolate a proof; it need not touch an external service.
+- Where such a proof stays in a shared project, size its budget from a full contended run rather than from an isolated one. A budget that clears the isolated cost by a thin margin turns contention into a red gate reporting a timeout, which carries no diagnostic about the code and costs a full investigation to dismiss.
 
 ## Shared test infrastructure
 
@@ -188,6 +197,14 @@ Coverage rules:
 Before acceptance:
 
 - prove every intended test file is discovered by the correct project;
+- prove every declared project is reachable from a gate. A project registered in the root
+  configuration with no script, or with a script no chain runs, is a proof that never executes — and
+  because it never executes it never fails, so the suite reports green while carrying it. Read the
+  chain, not the exit code: run each project directly once and compare that list against what `test`
+  actually invokes. The gate that would report this gap is the gate that is missing.
+- prove a declared project's include resolves to a real file. An empty project is not a passing
+  project: Vitest exits non-zero on "no test files found", so a project aimed at a path that was
+  never created stays invisible until something finally runs it.
 - inspect actual test counts and environments;
 - audit `.todo`, `.skip`, conditional skips, retries, and inflated timeouts;
 - confirm each assertion would fail for the defect it claims to catch, and that it fails rather than passes when its population is empty;