AGENTS.md git:20261005.efa6f2aA

Immutable. This exact content never changes and is served at /api/v1/blob/0fd446b742576717.

# ROSClaw Agent Instructions

ROSClaw is physical-AI runtime infrastructure. Treat robot, ROS, actuator,
motor, and hardware commands as safety-sensitive. This file is safe for Codex,
Claude Code, OpenClaw, and other agent frameworks that read project guidance.

<!-- ROSCLAW-MANAGED-BEGIN -->
## Runtime boundary

- Project root: `.`
- Default robot: (none detected)
- MCP transport: `stdio`
- Pinned ROSClaw CLI: `.venv/bin/python -m rosclaw.entrypoint`; use it instead of another `rosclaw` on `PATH`.
- One-line setup: `rosclaw agent install --project-root . --skip-secrets`
- Codex activation: trust this exact repository, then run
  `rosclaw agent doctor codex --project-root .`.
- Claude Code activation: approve the project `rosclaw` MCP server.

## Tool policy

The ROSClaw MCP server exposes 22 read-only, body-context,
simulation, validation, guarded-action, and emergency tools. It exposes no raw
hardware primitive and gives the Agent no authority to approve its own REAL
request.

| Tool | Safety level | Purpose |
|------|--------------|---------|
| `get_robot_state` | S0 | Current body state and readiness |
| `list_skills` | S0 | Skills available to the runtime |
| `query_memory` | S0 | Retrieve similar past experiences |
| `validate_trajectory` | S2 | Plan validation, never real motion |
| `sandbox_run` | S1 | MuJoCo simulation preview only |
| `practice_query` | S0 | Query practice episodes |
| `emergency_stop` | S4 | Request daemon E-Stop; verify physical-stop evidence |
| `get_body_profile` | S0 | Static effective body profile |
| `get_body_state` | S0 | Body safety state and capability matrix |
| `list_body_capabilities` | S0 | Capabilities grouped by status |
| `query_body` | S0 | Answer questions about the current body |
| `validate_body_action` | S0 | Validate proposed body-level action |
| `get_calibration_status` | S0 | Calibration status for body components |
| `get_runtime_status` | S0 | rosclawd health and privilege-boundary status |
| `request_action` | S3 | Submit a guarded SHADOW or REAL action to rosclawd |
| `get_action_status` | S0 | Read daemon queue state and terminal receipt |
| `cancel_action` | S3 | Cancel queued work; active motion requires E-Stop |
| `get_product_status` | S0 | Canonical release and evidence boundary |
| `list_product_demos` | S0 | Official evidence-bearing simulation demos |
| `run_product_demo` | S1 | Run an official simulation and persist its receipt |
| `get_execution_receipt` | S0 | Read and integrity-check a receipt |
| `explain_execution` | S0 | Explain policy, execution, observation, and evidence |

## Robot Integration setup

- Robot Integration setup is an operator CLI workflow, not an MCP tool. Use
  `.venv/bin/python -m rosclaw.entrypoint robot discover --json`, `.venv/bin/python -m rosclaw.entrypoint robot install realsense --json`, and
  `.venv/bin/python -m rosclaw.entrypoint robot verify realsense --stage contract --json` for read-only
  discovery and signed-contract checks.
- Install native adapter dependencies or bind a live device only when the
  operator explicitly requests it. Offline configuration is not physical
  evidence, and local verification never promotes canonical support status.

## Capability Apps

- Apps are capability-only task manifests. Use `.venv/bin/python -m rosclaw.entrypoint app list` and
  `.venv/bin/python -m rosclaw.entrypoint app validate <APP> --json` for inspection.
- App installation grants no hardware access. Every step remains subject to
  rosclawd Session, Lease, Permit, policy, executor, and Receipt checks.

## rosclawd read-only inspection

- Inspect daemon health and the durable control ledger with
  `.venv/bin/python -m rosclaw.entrypoint daemon status --json`. Require `running` and
  `ledger.integrity_verified` to be `true`; require `ledger.write_failed`,
  `recovery.required`, and `emergency_stop_latched` to be `false` before
  relying on the control plane.
- Production REAL work also requires `supervision_state=ARMED`,
  `privilege_separated=true`, and `.venv/bin/python -m rosclaw.entrypoint daemon security-check --json` with `boundary_ready=true`,
  `daemon_uid_pinned=true`, and `ledger_state_private=true`. Same-UID
  development proves only a process boundary.
- Inspect an existing action with `.venv/bin/python -m rosclaw.entrypoint daemon action-status <ACTION_ID>
  --json` and `.venv/bin/python -m rosclaw.entrypoint daemon receipt <ACTION_ID> --json`.
- `daemon acknowledge-recovery` is an operator incident-review command. Do
  not invoke it as routine Agent automation; it does not clear E-stop or prove
  physical state.
- Session or Action Lease loss is terminal according to orphan policy. Do not
  recreate direct motion or reuse a Session from an earlier daemon generation.

## Safety

- Do not publish ROS topics, actuate hardware, run real robot skills, or mutate
  a live robot workspace directly. A user request or human confirmation does
  not make a shell/DDS/vendor command an approved execution path.
- Prefer fixture, mock, simulation, read-only, dry-run, or temporary
  `ROSCLAW_HOME` workflows for validation.
- Submit SHADOW or REAL work only through the MCP `request_action` tool backed
  by `rosclawd`. REAL requires an immutable body snapshot, a daemon-issued
  capability- and action-intent-bound permit, and a verified REAL executor. If
  any are unavailable, refuse the action and explain the missing prerequisite.
- Never instantiate `Runtime`, register a driver/executor, or open ROS, DDS,
  serial, CAN, or a vendor SDK from the Agent process.

## LeRobot Bridge v1.0.1

LeRobot is a policy backend inside ROSClaw. Do not operate its worker,
robot transport, executor, serial device, or vendor SDK directly.

### Discovery

1. Call `get_product_status`.
2. Call `get_runtime_status`.
3. Call `get_body_profile` and `get_body_state`.
4. Call `get_calibration_status`.
5. Check that `rh56.single_step` is available before requesting RH56 motion.

### Supported Reference Path

- Policy: `rosclaw_rh56_reference`
- Bodies: `inspire_rh56_left`, `inspire_rh56_right`
- Modes: proposal-only, SHADOW, single-step REAL
- REAL is submitted only through MCP `request_action`.

### Safety

- Use SHADOW before REAL.
- Never run `rosclaw lerobot rollout execute` from an Agent process.
- Never open serial/CAN devices directly.
- Never create or approve a Permit.
- Read `get_execution_receipt` and `explain_execution` before claiming success.

<!-- ROSCLAW-MANAGED-END -->

## Repository checks

```bash
python -m compileall -q src tests
ruff check .
ruff format --check .
mypy --config-file .github/mypy-ci.ini src/rosclaw/daemon src/rosclaw/mcp/adapters src/rosclaw/mcp/onboarding src/rosclaw/agent_runtime/mcp_hub.py src/rosclaw/connectors/ros/mcp/tools.py src/rosclaw/core/runtime.py src/rosclaw/cli.py src/rosclaw/body src/rosclaw/firstboot src/rosclaw/hub
pytest tests/practice -q
```

Use the repo skill at `.agents/skills/rosclaw/SKILL.md` for deeper CLI,
Practice evidence, MCP, and agent-framework workflows.

## ROS Expert Harness

- Read-only engineering: `ros inspect-system`, `ros diagnose`, `ros resolve`, `ros context`, `ros mission plan` through the pinned CLI. Use a temporary ROSCLAW_HOME for smoke tests.
- Optional canonical MCP extension: `ROSCLAW_ROS_EXPERT=1` adds four read-only composite tools; it grants no ROS write access.
- Keep source/time/hash/completeness visible. Historical snapshots are not live state. Graph inference does not replace Body/e-URDF truth.
- Physical actions still require rosclawd request_action. A synthetic coverage mask or successful action is not mission verification.
- Native DDS fixture acceptance is not Nav2/Gazebo cleaning acceptance. Actual Native single-input Gazebo cleaning has SIMULATION acceptance. Same-model A/B and hardware gates remain unaccepted; see docs/reports/ros-expert-harness/FINAL_IMPLEMENTATION_REPORT.md.