CLAUDE.md ยท diff
git:20260709.b2638bd to git:20260723.6e5370b
5 added, 4 removed. Audit A to A.
# 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 wrappers, authoring tools, generated contract
- validators/types, client helpers, host adapters, and product integration glue.
- They must not regain trusted local execution fallback behavior.
+ 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:style
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.