ceca51b0d8
Default humanoid intake to command-following gait and support bounded Cartesian target dragging for arms. Carry model and actuator semantics through calibration, native verification and packaging. Document reusable intake decisions and cover them with regression tests.
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# Repository working rules
|
|
|
|
The project is a generic robotics onboarding, simulation, and training platform.
|
|
Choose an intake route in [Workflow](docs/WORKFLOWS.md). Use
|
|
[Usage](docs/USAGE.md) for commands and [Contributing](CONTRIBUTING.md) for layout.
|
|
|
|
Apply the mandatory [per-robot skill maintenance rule](AGENTS.md#maintain-skills-after-every-robot-intake)
|
|
to every intake.
|
|
|
|
## Checks
|
|
|
|
Run from the repository root with the editable install active.
|
|
|
|
```bash
|
|
python -m pip install -e ".[dev]"
|
|
python -m pytest tests/ -q
|
|
python -m ruff check .
|
|
python scripts/train.py --list
|
|
```
|
|
|
|
For a host with unrelated pytest plugins on its Python path, run pytest in the
|
|
project environment with `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`. Use
|
|
[agent setup](docs/AGENT_SETUP.md) if imports resolve to a different checkout.
|
|
|
|
## Architecture
|
|
|
|
- The root and `rl/` are separate package roots. `rl/` has no `__init__.py`.
|
|
Keep imports from `mjrl`, `mjlab`, and `rsl_rl` in their existing form and
|
|
use the editable install to resolve them.
|
|
- `mjrl.backend.select.use_backend` must run before creating an environment.
|
|
The manager resolves mjlab's simulation class when it builds the environment.
|
|
Native MuJoCo implements the batched simulator interface that Warp provides.
|
|
- Native rollout scratch data is per worker. Restore each environment's state,
|
|
controls, and warm starts from its own buffers. Constant recomputation uses
|
|
dedicated scratch data and preserves visual statistics.
|
|
- `tasks/registry.py` discovers literal `tasks/<robot_id>/robot_spec.py`
|
|
files. Listing tasks must stay free of simulation imports. The selected
|
|
family resolves to a locked template in `tasks/templates/`.
|
|
- Keep physical facts in the robot specification and asset. Keep reward and
|
|
observation logic, randomization, curriculum, and PPO in the templates.
|
|
Adding a robot requires no changes to a template or a command entry point.
|
|
- Onboarding and verification are in `rl/mjrl/onboarding/`. Deterministic
|
|
controls live in `rl/mjrl/controllers/`, and the portable native runtime
|
|
lives in `rl/mjrl/platform/`. The legacy Rust controller and target build
|
|
tools remain in `deploy/`.
|
|
|
|
## Changes and verification
|
|
|
|
- Preserve the lock in `tests/test_template_lock.py`. Review an authorized
|
|
template revision before updating the recorded hashes, including shared
|
|
dependencies that change template behavior.
|
|
- Verify physics and control response separately. Report measured outcomes with
|
|
the model, backend, and run size. A shape check, a visual preview, or a
|
|
completed iteration alone cannot establish behavior or hardware readiness.
|
|
- Keep changes to vendored libraries identifiable with an `[mjrl]` marker,
|
|
reason, and upstream version. See [Vendoring](docs/VENDOR.md).
|
|
- Write repository material in English. A Chinese `*.zh.md` translation
|
|
carries the digest of its English source. Update both before refreshing the
|
|
marker with `tools/checks/stamp_translations.py`.
|
|
- Exercise tests against the quiet failure they claim to prevent. When an
|
|
assertion could pass vacuously, include a control that demonstrates detection.
|