CLAUDE.md git:20260723.6e5370bA

Immutable. This exact content is served forever at /api/v1/blob/647fd96d30fb0d4f.

# runx OSS Claude Contract

Read `AGENTS.md` first when working through a scafld spec. For direct code
cleanup, follow this file plus `CONVENTIONS.md`.

## Architecture

Rust owns the trusted local runtime path:

- `runx-contracts` owns public contract types and schema emission.
- `runx-core` owns pure state-machine and policy decisions.
- `runx-parser` owns pure skill, graph, runner, and tool manifest parsing.
- `runx-receipts` owns canonical receipt hashing, signatures, and tree proof.
- `runx-runtime` owns impure local execution, adapters, sandbox planning,
  harness replay, journals, registry clients, payment gates, MCP, and receipts.
- `runx-cli` is the native command shell over `runx-runtime`.

TypeScript packages are generated contract validators/types, distribution and
client wrappers, language-neutral extension helpers, host adapters, and product
integration glue. Skill authoring belongs to the native authoring service and
Skill Lab. TypeScript must not regain a second authoring path or trusted local
execution fallback behavior.

## Commands

Use the narrowest useful check while iterating:

```bash
pnpm typecheck
pnpm rust:crate-graph
pnpm verify:fast
```

For Rust-focused checks:

```bash
cargo fmt --manifest-path crates/Cargo.toml --all --check
cargo check --manifest-path crates/Cargo.toml --workspace --all-targets
cargo test --manifest-path crates/Cargo.toml -p runx-receipts
```

Avoid running multiple heavy Rust gates in parallel; this workspace has had
false timeouts when the eval binary is starved.

## Release Discipline

`cli-vX.Y.Z` is the CLI distribution version only. It may stamp/publish
`packages/cli`, native npm packages, and the `runx-cli` crate. It must not stamp
or publish internal Rust library crates unless the operator explicitly requests a
separate library-crate release.

Do not bump another patch to fix a broken release channel. Repair the existing
release asset, channel manifest, or workflow in place, and validate the manifest
against the actual archive contents before claiming the channel is live.

## Spec Workflow

Use scafld for non-trivial scoped work:

```bash
scafld plan <task-id> --title "Title"
scafld harden <task-id>
scafld approve <task-id>
scafld build <task-id>
scafld review <task-id> --provider claude
scafld complete <task-id>
```

`--provider local` is smoke-test only and cannot satisfy completion.

## Boundaries

- Do not touch another active spec unless the user explicitly assigns it.
- Do not add compatibility aliases, fallback runtime paths, or `.v2` contract
  ids for governed wire shapes.
- Do not duplicate runtime logic in TypeScript when the Rust runtime owns the
  path.
- Keep pure crates free of filesystem, network, subprocess, async runtime, and
  adapter concerns.
- Treat fixtures as parity evidence. Regenerate only when the semantic change
  is intentional and reviewed.
- For stateful hosted apps, keep OSS contracts and skills generic: use
  `runx.effect.transition.v1` with `effect_family` and `operation`; do not add
  product-specific authority families, packet namespaces, or Rust branches.
- For loop orchestration, keep the loop host outside the kernel. runx owns
  bounded governed turns, `allowed_tools`, `context_skills`, approvals, and
  receipts; the app/orchestrator owns scheduling, durable loop state, wakeups,
  projections, and stop policy. Do not add a resident loop engine or loop packet
  namespace to core.