git:20260803.0993e04 to git:20260908.0ff743d

- # 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, process invocation and

- supervision, 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.