Skip to content

CLAUDE.md

Latest commit

 

History

History
88 lines (68 loc) · 3.24 KB

CLAUDE.md

File metadata and controls

88 lines (68 loc) · 3.24 KB
Raw

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.

Commands

Use the narrowest useful check while iterating:

pnpm typecheck
pnpm rust:style
pnpm rust:crate-graph
pnpm verify:fast

For Rust-focused checks:

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:

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.