@orkestrel/scaffold 0.0.28 → 0.0.30

package/dist/host/AGENTS.md

@@ -157,3 +157,15 @@ This governs prose everywhere: chat replies, instruction files, guides, TSDoc, c
 - Keep all substance, nuance, and precision. Cut only what makes text hard to read.
 - Present a tradeoff as option, cost, and recommendation — not as a balanced meditation.
 - Write requirements so they are specific and testable. Replace evaluative words such as "user friendly" or "hardened further" with the concrete condition that closes them.
+
+#### Instruction files
+
+`AGENTS.md`, `.claude/rules/*`, `.agents/*`, `.claude/agents/*`, and every skill are executed, not
+read. An agent loads them mid-task and acts on them. Write them for that reader.
+
+- Write every line as a directive: what to do, what to check, or what to refuse. Delete a line that does none of the three.
+- Name the observable trigger and the required action. "When X, do Y" is actionable; "X matters" is not.
+- State the finding as the rule. Never record how it was found, which session found it, what was tried first, or what a probe proved. That history belongs in the commit message.
+- Cut any clause written to persuade, reassure, or explain the rule to a person. An agent needs the rule and its trigger, not agreement with it.
+- Give a rule one home. Restating it elsewhere creates two copies that drift, and an agent reading the stale one is following this file.
+- Keep an example only when it disambiguates the rule. Delete an example that merely illustrates it.

package/dist/host/agents/orchestration.md

@@ -91,6 +91,12 @@ Record the substitution.
 - Never assign Grok to either lane in Claude Code or Codex. If the remaining native engine is also
   unavailable there, the pass cannot run: stop and report rather than substituting Grok.
 - Grok takes both lanes only in Cursor, and only when Opus 5 and Sol are both unavailable.
+- Treat a lane that returns no verdicts as a lane that did not run. A bench lane reporting that its
+  driver executed and its engine was never reached is a dark bench, not a result. Record the bench
+  dark from that report, re-run the lane on the substitute engine from the table above, and name in
+  the routing ledger which lane ran on which engine. Never accept a round with one lane empty.
+- Re-read bench liveness at dispatch, not at session start. A bench that probed live can be dark when
+  the lane launches.
 
 ## Tedious work goes to Grok
 
@@ -617,17 +623,25 @@ 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
+- Run `npm login` before any publish. `npm publish` does not open the browser flow: unauthenticated
+  it returns `E404` on `PUT`, which reads as a missing package rather than a missing credential.
+- 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.
+- Run the login and every publish under `script -qfc '<command>' <log>`. npm offers the approval only
+  when it sees a TTY; without one it fails `EOTP` with no way to answer.
+- Expect two approvals. `npmjs.com/login/cli/<id>` authenticates the session; `npmjs.com/auth/cli/<id>`
+  authorizes the publish and opens the five-minute window. Tell the user both are coming, or the
+  second link reads as the first having failed.
+- Confirm authentication with `npm whoami`, never with an exit code. The legacy fallthrough exits
+  zero.
+- Re-probe `whoami` immediately before opening the window. A stored credential expires mid-session,
+  so a session-start answer does not hold.
+- Surface each approval URL the moment it appears in the log. Say that approving the publish one
   opens a five-minute window covering the rest of the layer.
 
 ### Spending the window

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

@@ -36,18 +36,28 @@ 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/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 |
+| 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 package's features work together end to end across environments |
+| `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,
   so the mirror rule does not reach it; its scope is the directory it sits in.
+- An integration test is an end-to-end test: it composes the package's own features and drives them
+  together, through the public API, with no part of the system under test replaced.
+- Scope it by where the composition happens. `tests/integration.test.ts` drives features **across**
+  environments — core through server, core through browser, one environment's output consumed by
+  another. A nested `tests/src/<environment>/integration.test.ts` drives features **within** that one
+  environment.
+- Do not put a packaging, install, or distribution check in an integration test. What the tarball
+  contains is a different question from whether the features compose.
+- A test the mirror rule flags is a misplaced test until its placement is checked. Move it to the
+  location its scope names. Never widen the rule to accept it.
 - Give every nested `integration.test.ts` its own exact-path project entry. A glob such as
   `tests/src/**/integration.test.ts` double-claims a file another project already owns.
 

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

@@ -60,9 +60,13 @@ Define aliases in `tsconfig.json` first. `vite.config.ts` derives from `compiler
 - `*/types.ts`: public API contracts.
 - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
   `configs/src/*bin*` files. Shared logic remains in root configs.
-- `configs/helpers.ts`: the one permitted leaf under `configs/`. It imports nothing from the
-  workspace, which is what keeps it a leaf. Each `configs/src/*.config.ts` imports the root config
-  rather than the leaf, so shared build logic stays in one place.
+- `configs/helpers.ts` and `configs/browsers.ts`: the only permitted leaves under `configs/`. Each
+  imports nothing from the workspace, which is what keeps it a leaf. Each `configs/src/*.config.ts`
+  imports the root config rather than a leaf, so shared build logic stays in one place.
+- Keep `configs/helpers.ts` free of any dependency a core-only workspace does not declare. It is
+  vendored byte-identical to every workspace, so an import there must resolve in all of them.
+  `configs/browsers.ts` exists for that reason: it imports `playwright` and
+  `@vitest/browser-playwright`, and only a workspace with a browser environment is given it.
 
 Environment rules:
 
@@ -110,14 +114,14 @@ environment:
 The second axis is cross-cutting workspace proofs. Each one covers the whole workspace rather than
 one environment, so each is its own project:
 
-| Project       | Files                        | Proves                                                          | In `test` |
-| ------------- | ---------------------------- | --------------------------------------------------------------- | --------- |
-| `policy`      | `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law  | Yes       |
-| `config`      | `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs  | Yes       |
-| `guides`      | `tests/guides.test.ts`       | Every documented API exists and every public API is documented  | Yes       |
-| `conformance` | `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks   | Yes       |
-| `integration` | `tests/integration.test.ts`  | The built package works when installed and driven from outside  | No        |
-| `service`     | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real | No        |
+| Project       | Files                        | Proves                                                              | In `test` |
+| ------------- | ---------------------------- | ------------------------------------------------------------------- | --------- |
+| `policy`      | `tests/policy.test.ts`       | Every source file obeys the syntactic coding and placement law      | Yes       |
+| `config`      | `tests/config.test.ts`       | Root configuration resolves its aliases, projects, and outputs      | Yes       |
+| `guides`      | `tests/guides.test.ts`       | Every documented API exists and every public API is documented      | Yes       |
+| `conformance` | `tests/conformance.test.ts`  | Where this package drifts from the official tooling it tracks       | Yes       |
+| `integration` | `tests/integration.test.ts`  | The package's features work together end to end across environments | No        |
+| `service`     | `tests/service/**/*.test.ts` | The live external services this package drives, driven for real     | No        |
 
 `conformance` and `service` are two subjects, not two names for one. `conformance` measures this
 package against an official artifact it stays compatible with and drives nothing external: the

package/dist/host/guides/scaffold.md

@@ -191,6 +191,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `matchesOrchestrationPath`  | function | Test whether a path instructs or wires an agent rather than the toolchain.    |
 | `matchesRange`              | function | Test whether a declared range already admits a published version.             |
 | `nameToGuide`               | function | Derive the guide mirror path a package name answers for.                      |
+| `nameToRewrite`             | function | Derive the declaration rewrite a published face roll-up applies.              |
 | `planToSummary`             | function | Project a plan into its tally by artifact origin.                             |
 | `selectGroups`              | function | Select the groups a compile covers, in plan order.                            |
 | `selectHostPaths`           | function | Select the host paths a named workspace vendors.                              |
@@ -826,6 +827,17 @@ except the manifest.
 - One template artifact per configuration file the selection needs: the root `tsconfig.json` and
   `vite.config.ts`, plus a Vite config and a scoped TypeScript config per selected environment, and
   two more when `bin` is set.
+- One template artifact, `configs/browsers.ts`, for a workspace selecting `browser` on either axis.
+  It resolves the Chromium the Playwright provider launches, and the root `vite.config.ts` calls it
+  once into `browserOptions` and passes that to every `playwright()` provider it configures. The
+  precedence is `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`, `PLAYWRIGHT_CHANNEL`, the
+  managed Playwright Chromium, the container's bundled Chromium, a verified system channel, then the
+  platform default. An installed pinned revision returns empty options, so Playwright keeps its own
+  launch defaults. A pinned revision that is not installed falls through to a `chromium` alias or a
+  sibling `chromium-*` revision under the same browsers directory, because a managed container ships
+  one usable build for many Playwright versions. It is its own file rather than a block in the
+  vendored `configs/helpers.ts`, which every workspace receives byte-identical while only a browser
+  selection declares the `playwright` this module imports.
 - One template artifact per source and test file the selection needs: an `index.ts` barrel per
   selected environment, `main.ts` and `index.html` for an application browser, `tests/setup.ts`
   plus the host setup modules the selection reaches, and one entry test per axis project.