@bjoernrochel/sevro 0.1.0-rc.1

package/docs/extension-protocol-v1.md

@@ -0,0 +1,292 @@
+# Extension protocol v1
+
+This is the target public contract for `sevro.extension.v1`. Extensions are
+explicitly configured development tools. Installing one does not change
+built-in grading or grant it control of fixture isolation, execution,
+persistence, or cleanup. The executable is trusted by the operator; a process
+boundary alone is not a sandbox.
+
+[`extension-v1.schema.json`](../schemas/extension-v1.schema.json) validates the
+versioned request and response shapes. The engine also validates request IDs,
+negotiated capabilities, path containment, decoded content, and the source and
+configuration digests at runtime.
+
+## Transport
+
+The runner receives an extension command as an argv array and never interprets
+it through a shell. For each method it starts a fresh process, writes exactly
+one UTF-8 JSON request to stdin, closes stdin, and reads exactly one UTF-8 JSON
+response from stdout before process exit. The request and response are each
+limited to 8 MiB. Extra stdout, malformed JSON, an unmatched request ID, a
+nonzero exit, timeout, or an oversized message is a protocol error. Stderr is
+diagnostic only, bounded to 64 KiB in retained evidence; it cannot supply a
+result. The runner cancels the extension process group on interruption.
+
+Every request has this envelope. `describe` uses the stable
+`sevro.discovery.v1` bootstrap protocol; subsequent methods use the selected
+extension protocol:
+
+```json
+{
+  "protocol": "sevro.discovery.v1",
+  "id": "request-1",
+  "method": "describe",
+  "params": {}
+}
+```
+
+A response echoes `protocol`, `id`, and `method`, then supplies exactly one of
+`result` or `error`:
+
+```json
+{
+  "protocol": "sevro.discovery.v1",
+  "id": "request-1",
+  "method": "describe",
+  "result": {
+    "extension": { "id": "example.policy", "version": "1.0.0" },
+    "protocols": ["sevro.extension.v1"],
+    "requiredCapabilities": [],
+    "optionalCapabilities": [],
+    "graders": [],
+    "taskVerdictPolicies": []
+  }
+}
+```
+
+An error has `{ "code": "namespaced.code", "message": "bounded text" }`.
+An error response, process failure, or invalid response never becomes a
+successful grade. The engine retains the method, error class, and bounded
+diagnostic without copying secrets or unbounded extension output.
+
+## Negotiation and operations
+
+The engine calls `describe` first through the discovery protocol. The
+extension identifies its stable ID and version, supported protocol versions,
+required and optional capability IDs,
+grader IDs it supplies, and task-verdict policy IDs it supplies. Capability IDs
+are namespaced strings. The engine chooses one compatible protocol, verifies
+all required capabilities against its own and the selected host's capability
+registry, and records the negotiated set. An unknown required capability is an
+error. Unknown optional capabilities remain unavailable and cannot be used.
+The engine, not the extension, classifies whether instrumentation changes host
+execution. Future extension protocols still need a compatible discovery
+response or an explicitly selected bridge; an unsupported protocol cannot be
+guessed from a failed extension call.
+
+`resolve` receives the selected project root, selectors, and extension
+configuration. The CLI also supplies `host` with the candidate adapter's `id`,
+`model`, `effort`, and available `capabilities`. The engine capability
+`sevro.case.host-route` guarantees this context; extensions that depend on it
+must negotiate that capability. These are selected route facts for preparing
+cases, not observations of completed execution. Semantic and advisory judge
+routes are not candidate context. Older v1 callers may omit `host` when this
+capability is unavailable.
+
+It returns neutral case descriptions with stable IDs, prompts,
+an optional `followUpPrompt` for a second turn in the same host session,
+fixture and built-in check declarations, required evidence declarations, and
+namespaced extension data. Paths in case descriptions are resolved and
+validated by the engine against the declared project and case-source roots.
+An extension must negotiate `sevro.host.continuation` before resolving a
+continuation case, and the selected host must declare the same capability.
+The extension cannot add a hidden source root by returning an arbitrary path.
+Fixtures may contain inline files, a declared clean repository source, or a
+bounded generated Git history. Both Git fixture kinds support optional
+working-tree files, staged paths, committed scaffolding, bounded Git hooks,
+and fixture executables. Sevro validates overlay paths, refuses symlinks and
+repository metadata in repository clones, installs hooks and executables
+after its own commits, and includes these declarations in fixture identity. Repository-specific policy and
+custom setup remain in the extension.
+
+An extension that negotiates `sevro.fixture.setup` may return an optional
+`fixtureSetup` from `prepare`. It names an absolute executable and bounded argv,
+plus optional environment variables. Sevro runs that trusted command once per
+trial in the Git fixture after source history and working-tree files are built,
+before extension artifacts are mounted or the host starts. The command is never
+interpreted through a shell by Sevro; an extension may explicitly select a
+shell executable. `{{sevro.project}}` and `{{sevro.workspace}}` in environment
+values resolve to the declared roots at execution time. The symbolic values and
+command enter fixture and comparison identity, while retained configuration
+records only their digest. Setup has a two-minute limit, inherits no credential
+environment variables, and its output is discarded. Failure or interruption
+stops the run before host execution; it cannot become a passing assessment.
+Absolute path references in this protocol use `file:///` URLs so Windows and
+Unix hosts share one serialized form. Fixture-relative paths use `/` separators
+and cannot escape their declared root.
+
+`prepare` receives one resolved case, the chosen host and capabilities, the
+configured passive or enforced condition, and extension data. It returns
+fixture preparation artifacts and requested instrumentation IDs with
+parameters. The engine validates these requests before host execution and
+passes them to the host. It rejects unknown or unsupported IDs and rejects any
+execution-changing instrumentation in a passive trial. Requested and applied
+instrumentation are recorded separately. Host adapters declare supported IDs
+and whether each changes execution. A requested ID must be among the
+negotiated capabilities. The host receives the validated request and must
+report the same applied IDs and parameters; a mismatch fails execution. An
+execution-changing request also requires the host to confirm an enforced
+condition. Instrumentation parameters enter retained evidence and must not
+contain secrets.
+
+A Codex extension may also negotiate `sevro.codex.plugin-marketplace` and
+return `codexMarketplace` from `prepare` with `artifactRoot`,
+`marketplaceName`, and nonempty `pluginNames`. Every package file must be a
+Git-excluded preparation artifact below that fixture-relative root, including
+`.claude-plugin/marketplace.json`. Sevro checks the declared names, package
+paths, and local manifest sources before invoking the Codex plugin CLI. The
+declaration and artifact digests enter evaluation identity. The Codex host
+installs the marketplace and named plugins in its private home for each trial;
+no package is installed from an undeclared artifact. This fixture setup is
+available in passive trials because it does not add enforcement
+instrumentation.
+An extension that also negotiates `sevro.codex.explicit-invocation` may declare
+`codexSkillInvocation` with a plugin and skill in that package. The resolved
+prompts must contain `{{sevro.codex.skill_invocation}}` exactly once across
+both turns. Sevro
+renders the installed `$plugin:skill` token separately for each trial and the
+Codex host retains a bounded dispatch receipt only after a completed turn.
+Missing or repeated tokens, absent packaged skills, and unsupported hosts fail
+before candidate execution. Supporting skill reads remain separate evidence.
+
+For a repository skill, negotiate `sevro.codex.repository-invocation` and
+declare `codexRepositorySkillInvocation` with `skillName`. It is mutually
+exclusive with the plugin invocation declarations. Prepare the exact
+`.agents/skills/<skillName>/SKILL.md` as a Git-excluded artifact, and place
+`{{sevro.skill_invocation}}` exactly once across the prompts. Sevro renders
+`$skillName`, preserves repository scope in the host request, and records the
+declaration separately in configuration and evaluation identity. Missing mounts,
+repeated tokens, or absent negotiation fail before candidate execution. The
+Codex host verifies the repository mount and emits its normal bounded explicit
+dispatch receipt after a completed turn. No plugin package is required.
+
+For a Claude repository skill, negotiate `sevro.claude.repository-invocation`
+and declare `claudeRepositorySkillInvocation` with `skillName`. Mount the exact
+`.claude/skills/<skillName>/SKILL.md` as a Git-excluded preparation artifact.
+The bundled host advertises this capability only with
+`--claude-project-settings`; otherwise it rejects dispatch before execution.
+The neutral invocation placeholder must lead the initial prompt and occur once;
+Sevro renders `/skillName`. This declaration is mutually exclusive with all
+other invocation declarations and enters retained configuration and identity.
+The host validates the bounded mount without following symbolic links. Its
+`sevro.claude.repository-invocation` observation binds one native command, exact
+arguments, and the complete mounted body before the first assistant entry in
+the completed session. It retains only acceptance and ordered skill metadata.
+Missing or ambiguous session evidence yields a partial observation; later Skill
+calls cannot repair an unverified explicit repository dispatch.
+
+A Claude extension may negotiate `sevro.claude.plugin-dirs` and return
+`claudePluginDirs` with nonempty fixture-relative `artifactRoots`. Roots must
+be unique and must not overlap. Every file below each root must be a
+Git-excluded preparation artifact, and each root must contain
+`.claude-plugin/plugin.json`. Sevro passes only the declared roots and their
+verified artifact paths to a capable host. The declaration and artifact
+digests enter evaluation identity. The host remains responsible for loading
+the plugin directories and isolating its credentials from candidate tools.
+An extension that also negotiates `sevro.claude.explicit-invocation` may
+declare `claudeSkillInvocation` for a skill present in one of those packages.
+The resolved prompts must contain `{{sevro.skill_invocation}}` exactly once
+across both turns. Sevro renders the `/plugin:skill` token for each trial and
+passes the same token to the Claude host. The neutral placeholder also works
+with `codexSkillInvocation`; the older
+`{{sevro.codex.skill_invocation}}` placeholder remains supported for Codex.
+
+An artifact for a generated or cloned Git fixture may set `gitExclude: true`.
+Sevro mounts its verified bytes, adds only that exact artifact path to the
+fixture's `.git/info/exclude`, and retains the flag in artifact evidence and
+fixture identity. The flag is invalid for a non-Git fixture. It lets evaluator
+assets such as project skills remain visible to the host without appearing as
+candidate changes in Git status checks.
+Artifact mounts refuse existing files and any parent that is a symlink or
+non-directory, including paths created by fixture setup or a cloned repository.
+An artifact may set `executable: true` to install its verified bytes with owner
+execute permission. The flag enters fixture identity and retained artifact
+references; absent or false leaves the file readable without execute permission.
+
+`evaluate` receives one completed or failed trial's bounded host observations,
+their source and completeness, built-in check results, artifact references,
+and the extension's namespaced case data. It returns namespaced checks and
+metrics. A check is `passed`, `failed`, or `unavailable`; it names the evidence
+used. A missing required observation remains unavailable. The extension may
+return a task-verdict recommendation only when an explicitly configured
+task-verdict policy names that extension policy. In that case, `evaluate`
+receives `selectedTaskVerdictPolicy` and must return a recommendation. The
+engine uses it only for a completed trial with completed grading and available
+required evidence. It retains the selected policy and each trial's
+recommendation. An omitted recommendation is a grading error. A policy may
+change a failed check's task verdict, but cannot conceal execution failure,
+grader error, or unavailable required evidence.
+Host adapters can supply additional namespaced observations. The engine bounds
+and retains those records, then passes them to `evaluate`. Required observation
+IDs must be present with `complete` evidence before a task can pass.
+Host adapters can also supply bounded evidence artifacts. The engine persists
+their bytes outside the candidate workspace before `evaluate`, then passes
+file URLs and digests through the existing artifact references. A required host
+artifact must be present before a task can pass.
+
+The methods are stateless. Every request carries the configuration and prior
+extension data it needs. The runner verifies extension identity and source
+digest for the run; a changed executable or configuration cannot silently
+continue the same run.
+
+The session client in [`extension-session.ts`](../src/extension-session.ts)
+implements discovery, `resolve`, `prepare`, and `evaluate` as separate process
+calls. Its caller declares the extension source-file closure; the client also
+includes the executable and hashes that closure before discovery and before
+and after later calls. The redacted configuration and command argv affect the
+configuration digest. Command argv must not contain credentials. A passing
+extension check must cite available, complete evidence. The engine now accepts
+inline and declared clean-repository cases with additive extension checks, runs `prepare` before the host,
+and persists check outcomes, evidence references, and metrics before fixture
+cleanup. It applies and retains bounded inline preparation artifacts after
+checking their path and digest. Source references require a caller-declared
+ID-to-file-URL map under a case source root and receive the same checks.
+The bundled Codex host currently advertises no instrumentation capabilities.
+
+## Grading and replacement
+
+The runner provides built-in shell, regex, JSON/schema, combined output,
+semantic-output, and
+advisory quality graders. A run can use those without any extension. An
+extension's graders add checks and metrics by default. The run configuration
+must explicitly name each built-in grader it replaces, or explicitly select
+one advertised task-verdict policy. Unknown or duplicate replacement IDs are
+errors. Retained evidence lists every active grader, its identity and route,
+and any replaced default.
+
+An extension may also return namespaced `domainOutcomes` with passed, failed,
+or unavailable status, evidence references, and bounded domain data. Sevro
+validates their evidence and retains them separately from task checks. They do
+not change the task verdict. Older evidence without this field leaves domain
+outcomes unknown.
+
+When a built-in grader is selected for replacement, the engine validates its
+declared check configuration but does not run its checks. It requires at least
+one declared, advertised extension check, and grades those checks instead.
+Unselected built-in checks stay active. The replacement list enters extension
+configuration and evaluation identity; evidence retains the selected defaults
+and omits them from active graders and trial check results. A replaced shell or
+semantic grader does not require its usual isolation or host route because it
+does not execute.
+
+An extension cannot replace execution status, grading status, or the evidence
+availability rules. It cannot turn an error or missing required evidence into
+a successful task assessment. A prompt without success criteria produces
+execution evidence and a task verdict of `not_assessed`.
+
+## Lifecycle
+
+The engine orders each trial as follows:
+
+1. Negotiate protocol and capabilities; resolve the case.
+2. Prepare the fixture and extension inputs; validate instrumentation against
+   the host and passive/enforced condition.
+3. Execute or resume the host and collect bounded observations.
+4. Run built-in checks, then extension grading, then compute separate
+   execution, grading, and task states.
+5. Persist complete trial evidence before fixture cleanup.
+
+On cancellation or failure, completed trials remain persisted and partial
+attempts retain an explicit incomplete or diagnostic state. The engine owns
+process-group cancellation and cleanup even when an extension fails. A dry
+run records preparation but no observed behavioral success.

package/docs/fixture-cleanup-validation.md

@@ -0,0 +1,70 @@
+# Permission-locked fixture cleanup
+
+The Darrow extraction comparison exposed a cleanup difference: its legacy
+fixture destroyer removes permission-locked directories, while Sevro retained
+them after a completed trial. Sevro now restores owner access inside completed
+candidate workspaces when needed. It clears their contents after trial evidence
+is retained, keeps empty reservations until active peers drain, and then removes
+the completed roots. Directory traversal uses link metadata and skips symbolic
+links; external targets retain their permissions and contents.
+
+## Public CLI regression slices
+
+The public seam is `sevro run --case-file ... --adapter-module ...`, as documented
+in [Development CLI](development-cli.md). Each controlled adapter uses real
+filesystem permissions and returns its workspace path as a bounded observation.
+The test reads retained public evidence and verifies that the workspace is gone.
+A preliminary internal-engine test was diagnostic only; it is not part of this
+TDD trace and was removed before implementation.
+
+Red — `bun test tests/cli.test.ts --test-name-pattern 'CLI removes a permission-locked candidate directory'`: completed evidence existed, but the mode-000 child directory kept the workspace present.
+
+Green — `bun test tests/cli.test.ts --test-name-pattern 'CLI removes a permission-locked candidate directory'`: the workspace was removed and retained evidence still agreed with the CLI result.
+
+Red — `bun test tests/cli.test.ts --test-name-pattern 'permission-locked candidate directory \(root\)'`: a mode-000 workspace root remained present after completion.
+
+Green — `bun test tests/cli.test.ts --test-name-pattern 'permission-locked candidate directory \(root\)'`: the workspace root was removed after evidence retention.
+
+Red — `bun test tests/cli.test.ts --test-name-pattern 'permission-locked candidate directory \(readable root\)'`: the readable mode-500 root lacked write access and remained present.
+
+Green — `bun test tests/cli.test.ts --test-name-pattern 'permission-locked candidate directory \(readable root\)'`: restoring owner write access allowed cleanup; the external link target's mode and bytes were unchanged.
+
+Each final example also links to an external directory with a read-only file.
+All three check that its directory mode, file mode, and file contents stay intact.
+These are deterministic filesystem and lifecycle checks, with no live model call.
+
+## Final source gates
+
+`bun test` passed all 243 tests and 1399 assertions across 38 files in 93.83
+seconds. The gate includes parallel admission, peer isolation, cancellation,
+failed persistence, extension lifecycle, and generated/repository fixture tests.
+`bun run typecheck` and `bun run format:check` pass.
+The full log and subsequent installed-archive checks are retained under
+`/Users/bjro/.darrow/issue95-fixture-cleanup/`. The tests ran on macOS with Bun
+1.3.13; they do not establish another platform or native model route.
+
+## Canonical workspace follow-up
+
+Darrow's private fixture builder also checked that its returned path was
+canonical. An initial diagnostic assertion in the cleanup examples exposed
+Sevro's logical temporary-directory alias; those diagnostic additions were
+removed before the isolated regression. The public canonical-workspace test
+records the operating system's `realpath` through a controlled host and compares
+it with the received workspace in retained evidence. The full source gate above
+predates this follow-up.
+
+The public CLI contract was clarified before implementation. Candidate and
+semantic workspace allocations now resolve the new directory through `realpath`
+before reservation, preparation, or host execution.
+
+Red — `bun test tests/cli.test.ts --test-name-pattern 'CLI supplies a canonical candidate workspace'`:
+exit `1`; the received `/var/...` path differed from the operating system's
+`/private/var/...` path. One test failed with four assertions in 222 milliseconds.
+
+Green — `bun test tests/cli.test.ts --test-name-pattern 'CLI supplies a canonical candidate workspace'`:
+exit `0`; one test and four assertions passed in 228 milliseconds after the fix.
+
+The final `bun test` gate passed 244 tests and 1403 assertions across 38 files in
+94.77 seconds. Typecheck and formatting pass. The source log is retained at
+`/Users/bjro/.darrow/issue95-fixture-mounting/sevro-full-gate.log`. These remain
+deterministic macOS/Bun checks, without a live model or additional platform claim.

package/docs/identity-v1.md

@@ -0,0 +1,65 @@
+# Evaluation identity v1
+
+`sevro.identity.v1` binds retained evidence to the inputs that can change an
+assessment. Its `dimensions` object has exactly the fields required by
+[`run-evidence-v1.schema.json`](../schemas/run-evidence-v1.schema.json). The
+runner computes each `*Digest` from the relevant normalized content. It must
+not use a temporary path, run ID, or timestamp as an input.
+
+| Dimension                                  | Content represented                                                                            |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `runnerBuildDigest`                        | Exact installed package build or local runner source build.                                    |
+| `projectDigest`                            | Evaluated project revision and dirty content, or a content snapshot without Git.               |
+| `configurationDigest`                      | Evaluation settings with credentials replaced by secret-presence markers.                      |
+| `extensionDigest`, `extensionProtocol`     | Extension source closure and negotiated protocol, or both `null`.                              |
+| `caseDigest`, `fixtureDigest`              | Resolved case declaration and fixture contents.                                                |
+| `checksDigest`, `requiredEvidenceDigest`   | Declared checks and evidence requirements.                                                     |
+| `evaluatorDigest`, `graderDigest`          | Evaluator policy, grader versions, active selection, and replacements.                         |
+| `instrumentationDigest`                    | Requested instrumentation and expected application; trial evidence records actual application. |
+| `routeDigest`                              | Candidate, semantic, and advisory host/model/effort routes.                                    |
+| `condition`, `trialCount`, `passThreshold` | Declared condition and assessment sampling rule.                                               |
+
+Each structured component digest is SHA-256 of its [RFC 8785 JSON
+Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785.html) UTF-8
+bytes. The runner rejects values outside canonical JSON, including non-finite
+numbers and unpaired Unicode surrogates. The final evaluation digest is:
+
+```text
+SHA-256(UTF-8("sevro.identity.v1\n") || UTF-8(JCS(dimensions)))
+```
+
+The CLI derives `runnerBuildDigest` from sorted packaged file paths and their
+SHA-256 bytes under `src/`, `schemas/`, `docs/`, and `examples/`, plus `README.md` and
+`package.json`. For a Git project, `projectDigest` binds the revision and dirty
+patch digest without the checkout path. Without a revision it hashes a bounded
+file snapshot, excluding `.git`, results, and run-state storage. A caller may
+provide explicit 64-character digests for controlled development runs.
+
+The prefix separates this digest from component digests and future identity
+versions. An exact-repeat comparison requires equal identities. An ablation may
+deliberately differ on `condition` or instrumentation; its report must name
+those dimensions and verify that the intended controls match. Historical
+artifacts without a dimension cannot be silently assigned a current identity.
+
+Credential values, raw transcripts, and temporary output locations never enter
+the stored dimensions. A credential's presence can be recorded in a redacted
+configuration; its bytes are never retained in evidence or its digest input.
+The effective positive trial job limit is retained as `configuration.redacted.jobs`
+and enters `configurationDigest`. Changing parallelism changes evaluation identity,
+even when the condition, host route, trial count, and assessment threshold match.
+
+Extension runs retain the operator-supplied redacted extension configuration
+under `configuration.redacted.extensionConfiguration`, alongside
+`extensionConfigurationDigest`. The retained copy is the same snapshot used
+for extension configuration identity. Private configuration stays outside run
+evidence. Consumers can compare the visible configuration with their declared
+inputs without reconstructing the engine's component digest inputs.
+
+Hosts may supply explicit, redacted `configuration` values. Sevro retains them
+under `configuration.redacted.hostConfiguration`, keyed by the used candidate,
+semantic, or advisory role, and includes them in `configurationDigest`. Custom
+adapter authors must keep secrets out of this object. Bundled Codex roles record
+`sevro.codex.agent-concurrency-limit` as the captured positive integer or `null`
+for the host default. Configuration paths and unrelated TOML bytes are not
+imported settings; a relocated configuration with the same effective values
+keeps this component unchanged.

package/docs/native-controls.md

@@ -0,0 +1,29 @@
+# Native control observation v1
+
+The bundled Codex and Claude hosts advertise `sevro.host.native-controls` and
+retain an observation with that ID. It exposes host facts for extension policy:
+
+- `method: native_control_calls`;
+- ordered `calls` containing only `ordinal`, `namespace`, and `name`;
+- `acceptedAgentCount`, a verified Codex acceptance count or `null` on Claude;
+- `submittedExecCalls`, the Codex submitted-code count or `null` on Claude; and
+- `truncated`, which is `false` for a complete record and may be unknown (`null`)
+  for an incomplete Codex record.
+
+The observation's source is the executing host, not the extension. It keeps no
+tool arguments, task messages, command bodies, or results. Call labels prove an
+invocation attempt, not success. Extensions decide which calls are prohibited.
+An unknown acceptance count cannot establish agent acceptance.
+
+Codex projects labels and counts from its bound native-session observation and
+preserves its completeness. Incomplete counts remain `null`. Submitted code remains explicit: extensions cannot
+infer absence of controls inside code that this observer did not inspect.
+Claude records every tool-use label from the bounded stream, with namespace
+`claude`, without filtering to Skill or Agent. It requires a completed successful
+turn, valid unique tool-use IDs and names, and a non-truncated list of at most
+128 calls. Malformed, duplicate, failed, or excessive streams remain partial.
+Tool-looking text in arguments or output does not become a native call.
+
+Consumers must verify the source, completeness, shape, ordering, and counts
+before using an empty call list to establish absence. Missing or partial
+evidence cannot establish a negative assertion.

package/docs/releases.md

@@ -0,0 +1,88 @@
+# Releases
+
+Sevro releases are public npm packages named `@bjoernrochel/sevro`. The public
+command remains `sevro`, and npm archives use `bjoernrochel-sevro-<version>.tgz`.
+A release version is an
+exact semantic version; development versions containing `-dev` are not release
+candidates. Darrow pins the published version in development dependencies and
+its lockfile. Marketplace plugins do not depend on Sevro.
+
+## Candidate contract
+
+Prepare one candidate from the intended release tag and package metadata. The
+tag must equal `v<package version>`. Package metadata must identify the public
+repository, registry, distribution tag, and an owner-selected license with its
+nonempty `LICENSE` file. Prereleases cannot use npm's `latest` distribution tag.
+
+Preparation creates a new absolute output directory and never replaces an
+existing directory. It packs with lifecycle scripts disabled, retains the npm
+file inventory, and writes `release.json` and `SHA256SUMS` beside the tarball.
+The record identifies the package, version, release tag, distribution tag,
+tarball SHA-256 and npm SHA-512 integrity, and the preparation runtimes.
+Preparation does not publish a package or create a Git tag.
+
+The package installation check accepts `--tarball <absolute file>` to verify
+that exact candidate without repacking. The supplied tarball remains intact.
+Its installed name and version must match the source metadata. Installation,
+CLI execution, generic grading, prompt-only execution, release provenance,
+reporting, and supported deterministic native fixtures run without source Git
+metadata in the installed package.
+
+## Maintainer workflow
+
+1. Select the license, update `package.json` to the intended release version,
+   and commit those changes. Preserve the existing public schemas and document
+   behavior changes. For the first candidate, use `0.1.0-rc.1` with npm tag
+   `next`; a prerelease does not establish full Darrow migration completion.
+2. Run frozen installation, typecheck, formatting, and the full test suite.
+3. Prepare and test the exact candidate:
+
+   ```sh
+   bun run release:prepare --tag v0.1.0-rc.1 --output /absolute/new/release-directory
+   bun run test:package-install --tarball /absolute/new/release-directory/bjoernrochel-sevro-0.1.0-rc.1.tgz
+   ```
+
+4. Run Darrow's public integration against that same tarball:
+
+   ```sh
+   SEVRO_PACKAGE_TARBALL=/absolute/new/release-directory/bjoernrochel-sevro-0.1.0-rc.1.tgz bun run test:eval-runner-sevro-package
+   ```
+
+5. Review the changes, file inventory, retained checks, and compatibility
+   limitations before authorizing publication. Keep the reviewed tarball and
+   its checksums. Publish that artifact rather than repacking after review.
+6. After publication, verify registry integrity, install the exact version in
+   Darrow, and run its frozen installed compatibility gate. Retain the prior
+   version's evidence for updates. Roll back through a new dependency/lockfile
+   commit and rerun the installed gate; never relabel failed-version evidence.
+
+## Manual release workflow
+
+`.github/workflows/release.yml` runs only through explicit dispatch against a
+release tag. Its default prepares and checks the artifact. `publish: true`
+additionally publishes that verified artifact using npm trusted publishing.
+No push or pull-request event publishes a package.
+
+Before the first publication, an npm owner must establish the package and its
+publishing authorization. The initial reviewed tarball can be published
+manually with an authenticated npm account:
+
+```sh
+npm publish /absolute/reviewed/bjoernrochel-sevro-0.1.0-rc.1.tgz --ignore-scripts --access public --tag next
+```
+
+After the package exists, configure its trusted publisher for GitHub owner
+`BjRo`, repository `sevro`, and workflow filename `release.yml`. The workflow
+uses a GitHub-hosted runner, Node 24, npm 11.20.0, and job-scoped `id-token: write`.
+The package repository URL must match this public repository. See npm's
+[trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+The workflow checks the downloaded artifact's SHA-256 before publishing and
+retains its release record. Configuring an owner or workflow does not itself
+authorize this coding session to publish or push.
+
+The first local candidate is `0.1.0-rc.1`, using the owner-selected
+`BUSL-1.1` license. Its `LICENSE` preserves Darrow's terms and parameters,
+changing only the Licensed Work name and description to Sevro. Neither local
+checks nor a workflow file claim a remote CI run or publication. Darrow's exact
+registry pin, default caller switch, remaining workflow migrations, focused live validation, and
+generic runner removal remain separate extraction gates.

package/docs/report-v1.md

@@ -0,0 +1,32 @@
+# Generic report v1
+
+`sevro report` reads one or more retained `sevro.cli-result.v1` files and their
+referenced `sevro.run-evidence.v1` files. It validates both public schemas and
+checks run identity, exit category, case count, and trial references before
+reporting. Paths must be absolute and distinct.
+
+```sh
+sevro report --result-file /absolute/path/to/result.json
+sevro report --json --result-file /absolute/path/to/first.json \
+  --result-file /absolute/path/to/second.json
+```
+
+The default output is Markdown. `--json` emits one `sevro.report.v1` document,
+defined by [`report-v1.schema.json`](../schemas/report-v1.schema.json). Invalid
+inputs return exit 64 with a diagnostic on stderr. Reporting does not change
+the exit category of any input run; each row retains its original code.
+Pre-run failures with no case rows remain visible in the input-run section.
+
+Each case row keeps task verdict, execution, and grading separate. Task pass
+rate is measured only when every trial completed execution and grading with an
+assessed task verdict. Candidate duration sums the measured host call time
+across trials. Tokens and cost are totals only when every trial has complete
+usage and that measurement is present. Dry trials, incomplete usage, absent
+provider cost, and historical results without duration show `null` in JSON and
+`unknown` in Markdown. Missing values never become zero. The report retains
+exact candidate, semantic, and advisory routes and lists domain outcomes
+separately from the task verdict.
+
+Rows are descriptive, not matched comparisons. Darrow's skill activation,
+ablation matching, and benchmark interpretation remain repository policy and
+require their own report layer over these generic results.