@bjoernrochel/sevro 0.1.0-rc.8 → 1.0.0

package/docs/runtime-v1.md

@@ -1,8 +1,7 @@
 # Runtime configuration v1
 
-Configure access to existing host tools, private writable caches, native goals,
-and selected plugin hooks in `<project-root>/sevro.json`. This interface is
-available in `0.1.0-rc.3` and later.
+Configure access to existing host tools, private state, reusable caches, native goals,
+and selected plugin hooks in `<project-root>/sevro.json`.
 
 `--runtime-config-file /absolute/path/runtime.json` selects a replacement file.
 Sevro reads exactly one file before execution, including dry runs. It does not
@@ -14,6 +13,17 @@ non-symlink files of at most 64 KiB.
 
 The [JSON schema](../schemas/runtime-v1.schema.json) has format
 `sevro.runtime.v1`. All properties except `format` are optional.
+Start with the smallest file:
+
+```json
+{ "format": "sevro.runtime.v1" }
+```
+
+Then add `environment.inherit: ["PATH"]` for installed tools. Follow the
+[runnable runtime recipes](recipes.md#add-host-tool-access-one-capability-at-a-time)
+to add Node, Python/UV, mise, goals and selected plugin hooks separately.
+The following composed example is for a workflow that already needs all these
+capabilities:
 
 ```json
 {
@@ -26,7 +36,13 @@ The [JSON schema](../schemas/runtime-v1.schema.json) has format
     }
   },
   "runtime": {
-    "seedDirectories": [{ "source": "./public-uv-cache", "target": "uv-cache" }]
+    "sharedCacheDirectories": [
+      {
+        "source": "../public-uv-cache",
+        "target": "uv-cache",
+        "roles": ["candidate", "hooks"]
+      }
+    ]
   },
   "hooks": {
     "nativeGoal": true,
@@ -35,7 +51,7 @@ The [JSON schema](../schemas/runtime-v1.schema.json) has format
 }
 ```
 
-Create the example's `public-uv-cache` directory beside the configuration, or
+Prepare the example's `public-uv-cache` directory outside the project, or
 omit `runtime` when no prepared cache is needed. Selected plugin names must be
 present in the case's prepared mounts; remove names that the case does not mount.
 `DARROW_CACHE_DIR` is an ordinary explicit variable in this example, not a
@@ -144,8 +160,80 @@ minimal system read tree such as `/usr` or `/etc`, Sevro retains its explicit de
 the native preflight may refuse that overlapping setup rather than expose home
 contents.
 
+## Local HTTP test servers
+
+Sevro supports local HTTP servers in isolated Codex candidate
+commands and `sevro.shell` graders through an explicit operator selection:
+
+```json
+{
+  "format": "sevro.runtime.v1",
+  "network": { "localHttp": true }
+}
+```
+
+Add this property to the selected `sevro.json`, or select a replacement with
+`--runtime-config-file`. Declare the existing Node/Python installations through
+the environment and filesystem options above. The selection is snapshotted and
+enters evaluation identity. Absent or `false` preserves existing permissions.
+Hooks and semantic/advisory hosts keep their existing network permissions; this
+option applies to Codex candidates and shell grading.
+
+On macOS, shell isolation permits IP socket binding, loopback inbound traffic,
+and outbound connections to loopback addresses. Wildcard listeners such as
+Node's `server.listen(0)` work with loopback clients. Other outbound IP traffic
+remains denied. On Linux, shell checks retain their private network namespace
+with usable loopback and no external route.
+
+Codex uses its managed command network proxy with `allow_local_binding = true`,
+upstream proxy chaining disabled, and only `localhost`, `127.0.0.1`, and `::1`
+allowlisted. Its native sandbox permits local binding and loopback traffic while
+refusing direct outbound TCP. The native proxy may permit DNS queries; public
+HTTP destinations are not allowlisted. The candidate can reach other services
+on the available loopback interface, so choose this option for evaluations
+that need that access. It does not provide a separate per-trial loopback service
+namespace on macOS.
+
+The supported host boundary is the native Codex sandbox and its experimental
+`network_proxy` feature, documented in the [OpenAI permission reference](https://learn.chatgpt.com/docs/permissions).
+Setting `allow_local_binding` while leaving command networking disabled still
+denies `listen()` on macOS. Integration tests execute the installed native
+Codex sandbox, a wildcard HTTP listener and loopback client, and an outbound TCP
+denial probe. Host versions and actual upstream evaluation outcomes belong in
+[validation evidence](https://github.com/BjRo/sevro/blob/main/docs/evidence.md), rather than being inferred from a profile's
+text. An unsupported host must not be interpreted as a passing behavior test.
+
+## macOS ancestor metadata
+
+Sevro's macOS outer sandbox for isolated shell checks and authorized command
+hooks permits metadata reads on the exact ancestor paths of existing validated
+grants. This includes declared read-only support trees, private writable
+runtimes, and bounded transcript, candidate artifact, and managed workspace
+access. The permissions are derived automatically from those grants; no
+additional configuration is required. They let libc `realpath()` canonicalize
+paths inside a permitted subtree.
+
+Ancestor directory metadata, such as existence, type, ownership, permissions,
+and timestamps, is visible. Directory listings, ancestor file contents, and
+ungranted sibling metadata and contents remain denied under protected roots.
+Writes remain limited by the existing writable grants; read-only grants stay
+read-only. This metadata exception does not grant access to an ancestor subtree
+or change network isolation.
+
 ## Private writable state
 
+Codex candidate commands can write the isolated fixture's `.git` directory,
+including its index, refs, objects, and task-owned admission locks. Sevro grants
+that exact path explicitly because Codex's workspace permission otherwise keeps
+Git metadata read-only. Real commits and publication to a fixture-local remote
+need no additional runtime option. This grant does not authorize writes to
+source repositories, grading inputs, host authentication or configuration, or
+peer trials. Command network access remains disabled unless the operator selects
+the [local HTTP option](#local-http-test-servers).
+An existing fixture `.git` must be a physical directory. Symlinks and Git
+directory pointer files are refused before launch because their metadata may
+belong to a protected source repository rather than the isolated trial.
+
 `runtime.seedDirectories` copies prepared public dependencies into a private
 slot for each execution role. `source` uses the filesystem path rules above;
 `target` is a single lowercase slot name, up to 64 characters, with letters,
@@ -153,10 +241,12 @@ digits, and hyphens. `home` and `tmp` are reserved. Targets must be unique.
 An optional nonempty `roles` array selects any of `candidate`, `checks`, `hooks`,
 `semantic`, and `advisory`. For example, `"roles": ["candidate", "checks", "hooks"]`
 keeps dependency slots out of semantic and advisory runtimes. Without `roles`,
-execution and artifact-grading roles retain the existing selection. Response-only
+candidate, hook, artifact semantic, and advisory roles receive private copies.
+Shell checks require explicit `"checks"` selection; a non-UV grader receives no
+implicit UV/Python cache. Existing configurations whose shell checks need seeded
+dependencies must add `"checks"` to `roles`. Response-only
 semantic grading omits implicit seeds; include `"semantic"` explicitly in `roles`
-when that route needs dependencies. Artifact semantic grading and executable
-shell checks keep their declared tools and default seed selection.
+when that route needs dependencies. Declared host tools remain available to shell checks.
 
 Each source tree is bounded to 16,384 entries and 512 MiB. Escaping symlinks,
 directory cycles, dangling links, and special files are refused. File content
@@ -172,19 +262,64 @@ retaining large policies can retain up to the configured per-seed byte bounds.
 Source caches are never a writable runtime. Use prepared public caches rather
 than credential-bearing homes or evaluator directories.
 
+### Reuse a shared dependency cache
+
+`runtime.sharedCacheDirectories` opts into persistent writable caches without
+copying or hashing their contents for each trial. Each entry requires `source`,
+`target`, and a nonempty `roles` array drawn from the same five roles above.
+The source must already be an owned, readable, writable directory. Relative paths
+resolve beside the runtime file. Sevro resolves declaration symlinks to their
+canonical source and revalidates that directory before execution.
+Targets use the seed slot rules and must be unique across seeds and shared caches.
+Sources cannot overlap each other, private seed sources, declared read-only
+inputs, evaluated project/source trees, results, credentials, or native private state.
+
+Select only roles that actually use UV, for example `"roles": ["candidate", "hooks"]`.
+If a grader also uses UV, add `"checks"` to that same entry; both roles use the
+same cache. Each selected private slot aliases the original directory, with a
+narrow sandbox write grant. Other roles receive no slot or source grant.
+Shared content survives successful, failed, and cancelled trials and later runs.
+Sevro removes only disposable role state, never the declared shared source.
+
+Prepare UV packages once outside evaluation, point `UV_CACHE_DIR` at
+`{{sevro.runtime}}/uv-cache`, and reuse the existing Python installation through
+declared read-only tool roots. Set `UV_PYTHON_DOWNLOADS=never` to require that
+installation. Sevro keeps `UV_OFFLINE=1`; a missing dependency fails rather than
+downloading during a trial. Project virtual environments and temporary files
+remain disposable; UV's install/link mode can still allocate files in a virtual
+environment. The shared option removes the full cache copy per trial.
+
+Shared caches are mutable across trials, roles, and runs. Use them only for public
+dependencies and accept that a participant can change them for later participants.
+Use isolated seeds when dependency independence is required. Configuration identity
+binds the source, slot, and roles, but excludes mutable cache contents; equal
+identities therefore do not prove identical shared-cache bytes. Sevro does not
+age-delete shared caches. Manage their size between evaluations with the cache
+tool, such as `uv cache prune --cache-dir /absolute/public-uv-cache`.
+
 `{{sevro.runtime}}` in an environment value resolves to that role's writable
-root. Sevro supplies private `HOME` and temporary storage and sets `UV_OFFLINE=1`
-and `PYTHONDONTWRITEBYTECODE=1`. Candidate, hook, checker, semantic, and advisory
+root. Codex commands receive a `TMPPREFIX` inside their private `TMPDIR`,
+so zsh here-documents use their existing private temporary storage while shared
+host temporary directories remain denied. `TMPPREFIX` is runner-owned and cannot
+be inherited or set through runtime configuration.
+Sevro supplies private `HOME` and temporary storage and sets `UV_OFFLINE=1`
+and `PYTHONDONTWRITEBYTECODE=1`. Fixture setup uses the candidate commands'
+private `HOME`, so `$HOME` paths initialize the same state the candidate will
+use. Its temporary directory stays disposable.
+Candidate, hook, checker, semantic, and advisory
 state are separate. With a runtime policy, native candidate, semantic, and
 advisory roots live in a unique runner-owned host directory outside the Git
-fixture. The root contains `home`, `tmp`, and declared seed slots; plugins can
+fixture. The root contains `home`, `tmp`, private seed slots and selected shared-cache links; plugins can
 use paths such as `~/.darrow/reviews` without creating repository-local review
 state. Command runtime directories are separate from host authentication,
-configuration, and live transcript sources. Checker and hook caches also live
-outside candidate-controlled workspace state. Private roots survive native
+configuration, and live transcript sources. Checker and hook private state also lives
+outside candidate-controlled workspace state. Shared sources remain at their declared locations. Private roots survive native
 continuation turns and children, then are removed with their owning trial or
-host state after owned hooks terminate. Opted-in candidate artifact runtimes
-remain alive through grading as described below. Runs without a selected runtime policy
+host state after owned hooks terminate. Checker home, temporary storage, and copied
+seeds are removed after grading even when the fixture is retained after failure
+or cancellation. Results and evidence are preserved. Opted-in candidate artifact runtimes
+remain alive through grading as described below. Runs with neither fixture setup
+nor a selected runtime policy
 retain their previous writable-state locations.
 
 Claude refuses managed workspace or runtime namespaces overlapping its
@@ -200,8 +335,7 @@ data and remain trusted code responsible for their own execution boundary.
 ## Candidate artifact access
 
 Use `runtime.artifactDirectories` to let graders read selected artifacts in the
-candidate's private home after execution. This option is available in the current
-source checkout; published `0.1.0-rc.7` does not include it.
+candidate's private home after execution.
 
 ```json
 {
@@ -212,7 +346,8 @@ source checkout; published `0.1.0-rc.7` does not include it.
 }
 ```
 
-The example permits only the candidate-created `~/.darrow/reviews` subtree.
+The example permits only the `~/.darrow/reviews` subtree, which may be initialized
+by trusted fixture setup or created by the candidate.
 Its original absolute path reaches isolated shell checks and native
 semantic/advisory commands as `SEVRO_CANDIDATE_ARTIFACT_REVIEWS`. Graders keep
 their own private `HOME`; use the supplied variable to read candidate evidence.
@@ -228,12 +363,31 @@ to 16,384 entries, including its root. Missing directories, symlinked ancestors,
 descendant symlinks, hardlinks and special files make grading an error; missing
 evidence cannot produce a pass.
 
+Initialize an empty directory or seed prior Review state in the extension's
+trusted `fixtureSetup` command before the candidate starts. For example:
+
+```sh
+mkdir -p "$HOME/.darrow/reviews"
+printf '%s\n' '{"verdict":"passed"}' > "$HOME/.darrow/reviews/prior.json"
+```
+
+Setup and candidate commands share this private trial home, including when no
+artifact grants or runtime file are selected. Graders keep their own homes and
+receive only declared read-only artifact grants. To test missing reports or
+absence of new artifacts, initialize the directory without writing a report;
+an empty safe directory reaches ordinary task checks. Missing required reports
+can then fail those checks, while negative cases can assert the directory is
+empty. Sevro does not automatically create declared artifact directories: if
+setup and candidate both leave one absent, or replace it with an unsafe path,
+grading still errors. Setup state is temporary and is removed with its trial,
+including setup failure, cancellation, and dry runs.
+
 The grant permits reads and denies writes, creation, deletion and renaming.
 Credentials, other home contents and peer role/trial state stay protected.
 Ordinary `filesystem.readOnlyRoots` cannot select this private-state exception.
 Artifact grants and native transcript access are independent opt-ins.
 
-The trial allocates the retained runtime before launching its candidate and
+The trial allocates the retained runtime before fixture setup and
 removes it after grading, advisory review and evidence persistence, including
 failure and cancellation paths. Review state remains outside the Git fixture.
 These artifacts are temporary; declaring access does not copy their bytes into
@@ -248,6 +402,72 @@ hosts validate it before use. Grading adapters must preserve the read-only
 boundary. The directory declarations enter runtime configuration identity;
 per-trial absolute paths do not.
 
+## Candidate Codex configuration and user skills
+
+Set top-level `"codexState": true` to expose the bundled Codex candidate's actual
+isolated configuration and user-skill state. This opt-in is independent of
+`nativeTranscripts` and ordinary
+candidate-home artifact declarations:
+
+```json
+{
+  "format": "sevro.runtime.v1",
+  "codexState": true
+}
+```
+
+Candidate commands receive the real isolated `CODEX_HOME`. They may read its
+`config.toml` and write non-system skills below `CODEX_HOME/skills`. The native
+process's separate user-skill directory is available as
+`SEVRO_CODEX_AGENT_SKILLS`; it names that process's `HOME/.agents/skills`.
+Bundled `CODEX_HOME/skills/.system` skills remain read-only. Authentication,
+other private siblings, evaluator inputs and peer requests remain denied.
+Configuration remains read-only, and the preflight still checks credential denial.
+
+A physical fixture-local `.codex` directory is accepted only with this opt-in.
+Sevro marks the isolated project untrusted in its generated Codex configuration,
+so project-local configuration, hooks and rules remain represented inputs rather
+than effective host settings. The fixture is preserved. Diagnose the absolute
+`CODEX_HOME/config.toml`, not the checkout's `.codex/config.toml`. The runner's
+selected concurrency limit is written into the private config; an omitted limit
+still means the native host default, not a fabricated configured capacity.
+CLI model/effort and vetted-hook overrides keep their existing precedence; the
+file alone does not establish every effective native default or child route.
+
+After execution, isolated shell and native semantic/advisory graders receive
+read-only bindings to these original candidate paths:
+
+| Environment variable                            | Original candidate path                    |
+| ----------------------------------------------- | ------------------------------------------ |
+| `SEVRO_CANDIDATE_ARTIFACT_CODEX_CONFIG`         | Native `CODEX_HOME/config.toml` (one file) |
+| `SEVRO_CANDIDATE_ARTIFACT_CODEX_SKILLS`         | Native `CODEX_HOME/skills`                 |
+| `SEVRO_CANDIDATE_ARTIFACT_AGENT_SKILLS`         | Native process `HOME/.agents/skills`       |
+| `SEVRO_CANDIDATE_ARTIFACT_COMMAND_AGENT_SKILLS` | Command `HOME/.agents/skills`              |
+| `SEVRO_CANDIDATE_ARTIFACT_COMMAND_CODEX_SKILLS` | Command `HOME/.codex/skills`               |
+
+Native and command homes are separate. The runner initializes these actual
+skill locations before the candidate starts and retains their resulting state;
+it does not create replacement empty directories for grading. Graders keep their
+own homes and must use these bindings. To assert absence, require every selected
+directory to exist, then search for `SKILL.md`, excluding only the native Codex
+root's read-only `.system` subtree. Missing evidence is an error. Do not search
+the grader's home or retired fixture state.
+
+The five artifact names are reserved. Each binding belongs to one active trial
+and one native request; reuse by another host request is refused. The same
+canonical ancestor, entry-limit, symlink, hardlink and special-file checks as
+ordinary artifacts apply. Configuration cannot be replaced by a directory grant.
+The native home is retained through grading and removed with its trial, including
+failure and cancellation paths. Standalone host calls clean up immediately.
+These grants do not persist native files in run evidence; private absolute paths
+do not enter identity, while the `codexState` selection does. Other candidate
+hosts cannot supply this Codex evidence and fail grading when it is requested.
+
+For the Darrow doctor and undefined-skill cases, select this configuration with
+`--runtime-config-file`, preserve the doctor fixture's checkout value `99`, and
+replace the retired-state absence check with the four skill-directory bindings
+above. Keep the original repository, no-commit, activation and semantic checks.
+
 ## Goals and plugin hooks
 
 `hooks.nativeGoal` enables Claude's native goal Stop-hook path while preserving
@@ -272,6 +492,17 @@ instead of being skipped. The wrapper denies network access and protected
 roots and owns asynchronous hook cleanup. Native timeout/cancellation stops
 owned hook descendants before private state is removed.
 
+Prepared native plugin projections live outside the fixture in the current
+host request's private native state. Curated hook read grants validate the
+canonical projection layout, ownership, private state permissions, and binding
+to that request. Only the selected plugin subtree is readable; it stays
+read-only, and credentials, private siblings, and peer requests remain denied.
+Ordinary filesystem declarations cannot select this exception. Codex validates
+and filters installed plugins before enabling its runner-owned skill collector,
+including requests without a runtime policy. Plugin command handlers still
+require explicit hook authority. Projections are removed with their owning host
+request.
+
 Auxiliary `.mcp.json` and `.lsp.json` files and plugin mods are unsupported under
 hook authority. Manifest MCP/LSP declarations are removed from curated mounts.
 
@@ -339,7 +570,7 @@ run evidence. Extensions and external benchmarks consume the
 ## Evidence and compatibility
 
 `configuration.redacted.runtimePolicy` retains the selected environment,
-canonical read roots, seed digests, and hook declaration. The engine snapshots
+canonical read roots, seed digests, shared-cache declarations, and hook declaration. The engine snapshots
 this input once; it participates in `configurationDigest` and evaluation
 identity. Symbolic runtime placeholders remain symbolic in identity, while
 execution uses per-role paths. This binds declared setup and seed contents;
@@ -353,7 +584,8 @@ file contents do not. The same discovery and skip evidence reaches
 `sevro.host.runtime` observations.
 
 Bundled hosts supply `sevro.host.runtime` with the applied policy digest, role,
-environment names, read roots, and seed slots. `sevro.host.hooks` records source
+environment names, read roots, seed slots, and selected shared-cache declarations.
+Shared entries contain no content digest. `sevro.host.hooks` records source
 and effective plugin digests plus observed executions and their exit codes.
 An empty execution list does not prove hook activation. Partial lifecycle
 evidence remains partial. Cases can require these observations; missing required
@@ -363,7 +595,8 @@ task verdict.
 `--toolchain-bin-dir` and `--claude-uv-cache-dir` are deprecated. They keep their
 previous behavior with a warning when no runtime file is selected. Combining
 them with a runtime file fails before execution. Migrate to `environment`,
-`filesystem`, and private seed slots; removal is no earlier than `0.2.0`.
+`filesystem`, and either private seed slots or shared-cache declarations; removal
+is no earlier than `0.2.0`. The deprecated UV option continues to copy privately.
 See the [CLI reference](development-cli.md), [native hosts](native-hosts.md),
 and [identity contract](identity-v1.md).
 

package/docs/troubleshooting.md

@@ -3,18 +3,18 @@
 Start with execution, grading, task states, and stderr. A documented possible
 cause is not a diagnosis of your machine.
 
-| Symptom                                   | Check and next step                                                                                                                                       |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Command cannot run                        | Use Bun 1.3.13 and verify the local package/version. Read [installation](installing.md).                                                                  |
-| Project snapshot contains a symbolic link | Use a separate evaluated project directory as in [the tutorial](getting-started.md); do not include installed dependencies in a plain-directory snapshot. |
-| Exit 0 but no passing task                | Prompt-only/dry runs are `not_assessed`. Read [results](reading-results.md).                                                                              |
-| Exit 64 before execution                  | Check absolute paths, exclusive route options, configuration, and capabilities in the [CLI reference](development-cli.md).                                |
-| Grading unavailable                       | Inspect required evidence/completeness in [results v1](results-v1.md).                                                                                    |
-| Native authentication fails               | Check the exact release and private credential route. Read [native hosts](native-hosts.md).                                                               |
-| Native or shell isolation fails           | Verify macOS and `sandbox-exec`. Other platforms are unverified.                                                                                          |
-| Extension protocol fails                  | Return one matching stdout response; diagnostics use stderr. Read [protocol v1](extension-protocol-v1.md).                                                |
-| Schema freshness fails                    | Run `bun run schemas:generate`, then `bun run schemas:check`, from a checkout.                                                                            |
-| External links fail                       | Follow [network failure triage](documentation-quality.md#external-links).                                                                                 |
+| Symptom                                   | Check and next step                                                                                                                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Command cannot run                        | Use Bun 1.3.13 and verify the local package/version. Read [installation](installing.md).                                                                                                |
+| Project snapshot contains a symbolic link | Use a separate evaluated project directory as in [the tutorial](getting-started.md); do not include installed dependencies in a plain-directory snapshot.                               |
+| Exit 0 but no passing task                | Prompt-only/dry runs are `not_assessed`. Read [results](reading-results.md).                                                                                                            |
+| Exit 64 before execution                  | Check absolute paths, exclusive route options, configuration, and capabilities in the [CLI reference](development-cli.md).                                                              |
+| Grading unavailable                       | Inspect required evidence/completeness in [results v1](results-v1.md).                                                                                                                  |
+| Native authentication fails               | Check the exact release and private credential route. Read [native hosts](native-hosts.md).                                                                                             |
+| Native or shell isolation fails           | On macOS, verify `sandbox-exec`; on Ubuntu 24.04 x64, verify `bubblewrap` and Claude's `socat`. See [validated scope](native-hosts.md#validated-platform-scope). Windows is unverified. |
+| Extension protocol fails                  | Return one matching stdout response; diagnostics use stderr. Read [protocol v1](extension-protocol-v1.md).                                                                              |
+| Schema freshness fails                    | Run `bun run schemas:generate`, then `bun run schemas:check`, from a checkout.                                                                                                          |
+| External links fail                       | Follow [network failure triage](documentation-quality.md#external-links).                                                                                                               |
 
 ## The repository guide is missing
 

package/docs/typescript-quality.md

@@ -1,6 +1,7 @@
 # TypeScript quality
 
-`bun run check:typescript` is the local and CI acceptance command. It performs a
+`bun run check:typescript` is the complete local acceptance command. CI runs the
+same checks in parallel phases. The complete command performs a
 frozen dependency installation, checks the complete source inventory, verifies
 generated schemas, documentation contracts, formatting, type-aware lint and typing,
 checks the Codex guide evaluation in dry mode and runs documentation examples, exercises coverage
@@ -14,13 +15,44 @@ schemas, documentation contracts, formatting, lint and types without the full in
 or package installation. Install dependencies with `bun install --frozen-lockfile`
 first. Quality dependencies are development dependencies pinned in `bun.lock`.
 
+After frozen installation, `bun run check:typescript --phase <name>` runs one
+phase and checks the complete source inventory. Each phase reports its elapsed
+time, including when it fails. The complete command runs these same phases in
+order; `--fast` runs only `static` without installing dependencies.
+
+| Phase     | Checks                                                                                        |
+| --------- | --------------------------------------------------------------------------------------------- |
+| `static`  | Schema freshness, documentation contracts, formatting, type-aware lint and typing             |
+| `docs`    | All guide dry runs, tutorial examples and recipe checks                                       |
+| `tests`   | Coverage integrity controls, the complete instrumented Bun suite and both coverage thresholds |
+| `package` | Packed-package installation and installed CLI workflows                                       |
+
+Use the same prerequisites as the corresponding complete-gate checks. A single
+phase is partial evidence; full acceptance requires all four on the same candidate.
+CI assigns every test file to exactly one of four duration-balanced shards, then
+enforces both coverage thresholds on their combined counters over the complete
+production inventory. Local `--phase tests` and the complete command still run
+the suite in one process. See the [shard commands](../scripts/coverage/README.md#test-shards)
+for reproducing the CI split.
+
 ## Source dispositions
 
-[`typescript-sources.json`](../typescript-sources.json) explicitly lists every
-TypeScript and JavaScript source. The guard refuses new, missing or duplicated
-files and declarations outside the configured TypeScript project. Changing a
-source disposition requires review; adding a glob is not a substitute for the
-inventory. The coverage baseline includes the platform-reachable subset of
+The [inventory guard](../scripts/typescript-inventory.ts) derives every TypeScript
+and JavaScript source disposition from Git paths, following the
+[maintainer decision in #143](https://github.com/BjRo/sevro/issues/143#issuecomment-6382662399).
+It classifies `git ls-files --cached --others --exclude-standard -z` output using
+the checked path rules, so supported additions and staged renames or deletions
+need no manual manifest edit. Non-ignored untracked sources are included in local
+candidate checks; committed CI checkouts use their tracked paths. Declarations
+take precedence over directory roles, and only the validators in the shared
+[schema catalog](../scripts/schema-catalog.ts) receive the generated disposition.
+Unknown or ambiguous paths, missing tracked files, an incomplete generated set,
+and sources outside lint or typing are refused. An independent filesystem audit
+also refuses ignored authored sources rather than silently dropping them.
+Changing a disposition rule still requires review. Isolated coverage snapshots
+index their copied candidate independently, preserving additions and deletions
+without changing the source checkout's index.
+The coverage baseline includes the platform-reachable subset of
 `inventory.production`; `scripts/coverage/platform-scope.ts` names each excluded
 host-specific file. Every production file remains inventoried, typed and linted,
 and the opposite platform measures it. Current instrumentation supports authored
@@ -29,14 +61,14 @@ validators in `inventory.generated` are excluded from instrumentation and the
 coverage denominator. New `.tsx`, `.mts`, `.cts` or JavaScript
 production requires an explicit instrumentation and quality-policy change first.
 
-| Inventory      | Lint and typing                                                                                      | Test and coverage disposition                                                                                                                                                                        |
-| -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `production`   | Type-aware strict lint and strict compiler                                                           | All platform-reachable authored executable `src` statements and branch outcomes, including unimported files in that scope                                                                            |
-| `generated`    | CommonJS syntax parsing, exact `schemas:check` freshness, and checked `.d.cts` boundary declarations | Real Bun schema tests; the five declared generated validators are outside the coverage denominator                                                                                                   |
-| `declarations` | Type-aware lint and compiler                                                                         | Declaration-only files have no executable counters                                                                                                                                                   |
-| `tooling`      | Same type-aware lint and strict compiler; `.mjs`/`.cjs` use `checkJs` and explicit JSDoc contracts   | Durable public gate probes, schema freshness, release and installed-package tests; outside the runner-production denominator                                                                         |
-| `tests`        | Same type-aware lint and strict compiler, including fixtures                                         | Real Bun filesystem/process/protocol tests; outside the production denominator                                                                                                                       |
-| `examples`     | Same type-aware lint and strict compiler                                                             | Packaged demonstration host adapters are synthetic consumer fixtures, exercised by installed-package validation; they implement no runner behavior and are outside the runner-production denominator |
+| Inventory      | Lint and typing                                                                                      | Test and coverage disposition                                                                                                                                                                                                |
+| -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `production`   | Type-aware strict lint and strict compiler                                                           | All platform-reachable authored executable `src` statements and branch outcomes, including unimported files in that scope                                                                                                    |
+| `generated`    | CommonJS syntax parsing, exact `schemas:check` freshness, and checked `.d.cts` boundary declarations | Real Bun schema tests; the five declared generated validators are outside the coverage denominator                                                                                                                           |
+| `declarations` | Type-aware lint and compiler                                                                         | Declaration-only files have no executable counters                                                                                                                                                                           |
+| `tooling`      | Same type-aware lint and strict compiler; `.mjs`/`.cjs` use `checkJs` and explicit JSDoc contracts   | Durable public gate probes, schema freshness, release and installed-package tests; outside the runner-production denominator                                                                                                 |
+| `tests`        | Same type-aware lint and strict compiler, including fixtures                                         | Real Bun filesystem/process/protocol tests; outside the production denominator                                                                                                                                               |
+| `examples`     | Same type-aware lint and strict compiler                                                             | Packaged recipe adapters, extensions and evaluator checks are consumer examples, exercised by tutorial and installed-package validation; they implement no runner behavior and are outside the runner-production denominator |
 
 Generated AJV CommonJS is deliberately not rewritten to conform to authored-code
 rules. An earlier audit of the original four generated files using ESLint's
@@ -45,8 +77,8 @@ recommended JavaScript rules found 879 redeclarations, 281 useless assignments,
 generation freshness, typed public boundaries and runtime behavior remain checked.
 Generated compiler output is excluded from coverage because the coverage target
 measures authored runner behavior. This applies only to
-`src/generated/cli-result.cjs`, `extension.cjs`, `report.cjs`, `run-evidence.cjs` and `runtime.cjs`
-as explicitly declared in the inventory. This disposition does not apply to authored CommonJS, including
+the exact validator paths derived from the [schema catalog](../scripts/schema-catalog.ts),
+which also drives schema generation. This disposition does not apply to authored CommonJS, including
 the coverage capture hook.
 
 ## Types, functions and review
@@ -120,7 +152,7 @@ macOS `sandbox-exec`, Keychain and Apple metadata modules are excluded; on macOS
 `bubblewrap` module is excluded. Shared isolation and credential code is counted
 on both.
 
-Apple developer-tool discovery lives in `src/runtime-discovery-apple.ts`, which
+Apple developer-tool discovery lives in `src/runtime/discovery-apple.ts`, which
 the public loader imports only under its explicit Darwin guard. Linux excludes
 that exact native module; macOS measures it, and both platforms still typecheck
 and lint it. The provider lookup, bounded query and read-root safeguards remain
@@ -146,12 +178,24 @@ summary, process ledger, Bun test log, unmodified source snapshot, LCOV and HTML
 production files, branch exclusions, and exact projected counts.
 `coverage-raw.json` and the raw summary preserve all validated counters before
 platform projection.
+CI also retains `.quality/shards/<index>/` with each shard's source snapshot,
+process ledger, test log, raw and portable counters, and manifest. Process IDs
+remain scoped to their original shard. Aggregation verifies candidate contents,
+workflow run, platform, architecture, Bun version, instrumentation
+layout, and exact test assignments before combining counters with normalized
+source paths. Missing, repeated, incomplete, or mismatched shards fail the gate.
+Failed-job reruns can reuse successful shards from earlier attempts of the same
+workflow run; manifests retain each attempt, and rerun shards replace only their
+own artifacts. Another candidate or workflow run cannot supply missing evidence.
 `--coverage [Bun test arguments]` is a diagnostic measurement; it still enforces
 both thresholds and writes `.quality/coverage-targeted`, keeping it distinct from
 the full-suite evidence. Sparse runs are expected to fail the full denominator.
 
 The durable public probes are `--probe snapshot`, `--probe scope`, `--probe branch`,
 `--probe missing-reports`, `--probe integrity`, and `--probe source-map`.
+`tests/scripts/typescript-quality.test.ts` invokes each probe once during the suite;
+the phase entrypoint and shard merge do not rerun them. The commands remain
+available for targeted diagnostics.
 The scope probe records a zero-seeded baseline and merged real process report
 under `.quality/coverage-scope`; it verifies that ordinary generated CommonJS
 validation still runs. Branch and missing-report controls
@@ -167,21 +211,40 @@ Codex 0.160.1 and Claude Code 2.1.284 for deterministic native hook tests. Hoste
 CI targets `ubuntu-24.04` x64 with Bun 1.3.13 and Node 24.13.0. Its first
 successful hosted run is required before describing that environment as validated.
 GitHub documents the [Ubuntu runner labels](https://docs.github.com/en/actions/reference/runners/github-hosted-runners).
-Ubuntu installs `bubblewrap` and `socat` and runs the same native isolation cases;
-local macOS runs retain `sandbox-exec`. Windows remains unverified.
+Ubuntu installs `bubblewrap`, `ripgrep`, and `socat` and runs the same native isolation cases;
+local macOS runs retain `sandbox-exec`. The macOS quality and coverage gate is
+local-only; the hosted workflow does not run a macOS gate. Windows remains unverified.
+
+Ordinary changes and explicit workflow dispatches run the four canonical phases
+concurrently. The tests phase consists of four shard jobs followed by a combined
+coverage job. Each job installs locked dependencies; native host tools are
+installed for `docs` and the test shards, and UV and mise for `docs`. Each shard
+retains its evidence, and the combined `tests` job uploads `.quality` even when
+coverage fails. Shards do not cancel their siblings on failure. A new commit to
+the same pull request cancels its superseded workflow run; main pushes and manual
+runs have independent concurrency groups. The stable aggregate `TypeScript quality`
+status requires every phase and all four shards to succeed. A missing, cancelled,
+skipped or failed phase or shard cannot turn that status green.
 
-Ordinary changes and explicit workflow dispatches invoke the canonical gate,
-upload `.quality` even when coverage fails, and publish the stable aggregate
-`TypeScript quality` status. A cancelled or failed gate cannot turn that status
-green.
+CI caches Bun's package downloads by Bun version, OS, architecture and `bun.lock`;
+every job still performs frozen installation. The docs job and test shards also
+cache the installed Codex and Claude packages by OS, architecture and the setup
+script's content hash, which includes both pinned versions and their installation
+layout. There are no fallback keys for native tools. On a hit, setup copies the
+cached packages into a fresh temporary tool root and verifies both native versions
+before publishing their paths. The cache never contains credentials or replaces
+the isolation prerequisites or required checks.
 
 Release metadata changes follow [the release workflow](releases.md) and reuse a
 successful full gate from an ancestor on `main`, with identical code,
 dependencies, schemas, tests, and other quality inputs. The selector permits
 only version/distribution-tag changes and its exact release-file inventory.
-It verifies the original full-gate step, so a reused release run cannot serve
-as fresh test evidence. Release CI runs `check:typescript --fast`, records the
-tested source and CI run URL, and skips the test/coverage job. The aggregate
+It verifies each original phase job and its gate step, including every shard and
+the combined tests job for sharded runs, or a historical complete gate job and
+step. A partial matrix or reused release run cannot serve as fresh test evidence.
+Duplicate phase or shard jobs are ambiguous and refused. Release CI
+runs `check:typescript --fast`, records the tested source and CI run URL, and
+skips all four full-gate phase jobs. The aggregate
 status requires both verified prior evidence and successful static checks;
 missing, cancelled, failed, or ambiguous evidence cannot establish a pass.
 Reused results remain attributed to their original run rather than being

package/examples/recipes/candidate.ts

@@ -0,0 +1,26 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Trusted, deterministic participant for exercising the recipe's real graders. */
+const host = {
+  id: "recipes.deterministic",
+  model: "fixture-editor",
+  effort: "none",
+  async run({ workspace }: { workspace: string }) {
+    const task = await readFile(join(workspace, "README.md"), "utf8");
+    const failing = process.env.SEVRO_RECIPE_FAIL === "1";
+    if (task.includes("Fix add")) {
+      await writeFile(
+        join(workspace, "math.cjs"),
+        `exports.add = (a, b) => a ${failing ? "-" : "+"} b;\n`,
+      );
+    }
+    return {
+      finalMessage: failing
+        ? "Start with npm start on port 9000."
+        : "Run bun run dev on port 3000.",
+      complete: true,
+    };
+  },
+};
+export default host;