Imported from Cissou34730/robot-learning-autoresearch (AGENTS.md). Install upstream with npx skills add Cissou34730/robot-learning-autoresearch. Copyright stays with the author.

AGENTS.md

Repository operational contract: environment, commands, layout, ownership, validation and Git conventions.

The Researcher protocol is defined in research/program.md, the current task in research/scenario.md, and the available capability surface in research/instruments.md.

Environment

This repository uses a fixed Python stack built around MuJoCo, Gymnasium and Stable-Baselines3. Dependencies are human-owned: the Researcher may use the installed stack but may not install packages or modify pyproject.toml or uv.lock.

jello is available through the researcher environment for JSON and JSONL artifacts.

All project Python execution goes through uv run. Never invoke system python, python3, pytest or ruff, or the interpreter inside .venv.

uv run python <script>
uv run python -m <module>
uv run pytest <target>
uv run ruff <arguments>

Command ownership

uv sync                                  # Human: install the fixed dependencies
uv run python -m robot_learning.train    # Runner: train a policy
uv run python -m robot_learning.play --model <model.zip>  # Human: open the viewer
uv run pytest                            # Runner: complete test suite
uv run pytest tests/e2e                  # Human: slow end-to-end lifecycle suite
.\reset_research.ps1 -Mode Fresh -Force  # Human: reset campaign, preserve science

The human may add -RecipeRef <git-ref> to Fresh to restore the complete researcher-owned scientific surface from one resolved commit before creating an empty v4 campaign. This imports no trained policy or evidence. Baseline is the separate operation for restoring a prepared experiment-1 policy and its evidence. The reset wrapper and research launcher share a machine-wide mutex. Reset backups resolve through Git's administrative path and support linked worktrees. Failed resets are restored with the human-only -Recover <operation.json> -Force operation, which validates the recorded manifest before writing.

The Researcher session may inspect files and, when the current phase requires understanding code state or a code delta, use read-only Git. It may edit its owned surface, run lightweight analysis, and run targeted tests. It may not execute training, the generic evaluator, the viewer, the Runner, the final benchmark, repository-wide tests, mutating Git commands or dependency-management commands. The exact available operations are cataloged in research/instruments.md.

Legacy policy migration through research/migrate_policy_runtime.py is a human-only maintenance operation, never a Researcher experiment command.

Layout

• robot_learning/benchmark/ - human-owned final and task-reference contracts and evaluators.
• robot_learning/scenario/ - current scenario implementation and scientific measurement code, with protected adapters to the human-owned panels. The protected scenario/__init__.py is a minimal package initializer, not a scientific extension point; researcher-owned scenario modules import each other directly.
• robot_learning/training/ - learning-method implementation and artifact support.
• robot_learning/train.py, evaluate.py, play.py - generic application entry points.
• research/run_experiment.py - Runner CLI and lifecycle orchestration.
• research/runner_*.py - Runner protocol, execution, persistence, paths and console implementation.
• research/current_params.json - active runtime configuration overrides.
• research/results.jsonl - authoritative experiment history.
• research/EXPERIMENTS.md - generated human-readable history.
• research/brief.md - generated current Researcher context.
• research/evaluations/ - durable detailed development measurements.
• research/checkpoints/accepted/ and research/checkpoints/retained/ - readable legacy archive locations and durable reusable policy lineages. Version-4 campaign state names the independent working_lineage, best_known_lineage, and retained IDs; selected challenger artifacts are published under the campaign-scoped retained archive before cleanup.
• models/candidates/ - disposable training candidates.
• tests/benchmark/, tests/autoresearch/, tests/scenario/, tests/training/ - tests grouped by ownership domain.
• tests/e2e/ - human-owned end-to-end lifecycle checks that drive real Git repositories, the PowerShell entry points and complete runner runs. They are minutes slow, so pyproject.toml keeps them out of the default uv run pytest and out of every campaign-time suite selection.

Human-owned paths

The Researcher may read but not modify these paths through an experiment:

• AGENTS.md, research/program.md, research/scenario.md, research/instruments.md;
• run_research.ps1, researcher_session.ps1, researcher_copilot.py;
• research/run_experiment.py, research/reset_campaign.py, research/runner_*.py, research/build_research_brief.py, research/query_training_log.py;
• pyproject.toml, uv.lock;
• robot_learning/benchmark/;
• robot_learning/policy_runtime.py, research/migrate_policy_runtime.py;
• robot_learning/robots/two_joint_arm.py and robot_learning/robots/two_joint_arm.xml;
• robot_learning/__init__.py, robot_learning/robots/__init__.py and robot_learning/scenario/__init__.py (minimal protected package initializer);
• robot_learning/scenario/final_benchmark.py and robot_learning/scenario/task_reference.py;
• tests/benchmark/, tests/autoresearch/ and tests/e2e/.

Protection is enforced centrally by research/runner_protocol.py. A protected path takes precedence over any researcher-owned prefix.

Researcher-owned paths

• robot_learning/scenario/, except the protected files above;
• robot_learning/training/;
• robot_learning/train.py, robot_learning/evaluate.py, robot_learning/play.py;
• tests/scenario/, tests/training/;
• research/current_params.json;
• the phase deliverables research/proposal.json, research/evaluation_request.json and research/postmortems.md. During v4 post-training analysis, exactly one actionable request is submitted: a measurement request or a closure proposal with its postmortem.

Scientific analysis, diagnostics and temporary tooling must be created within a researcher-owned code prefix. They are ordinary experiment code: they travel with its code lineage and validation, and are not an ignored scratch surface.

Validation

Do not run repository-wide lint or format passes. Format only touched files.

The Runner's complete validation is syntax checking plus ruff check on changed Python files, JSON parsing for changed JSON files, and selected pytest suites. A fresh baseline and changes outside the positively declared researcher-owned surface receive complete validation. Researcher-owned code changes omit only tests/benchmark; parameter-only proposals and decisions without code changes run no suites.

Tests assert the behavior owned by their domain. Human-owned benchmark and AutoResearch tests remain method-neutral. Architecture guards derive the surface they protect rather than naming one implementation file. Adding harness regression tests does not itself broaden campaign-time suite selection for researcher-owned reward or parameter changes. A test that needs a real repository, a real PowerShell entry point or a complete runner run belongs in tests/e2e/, never in a campaign-time domain.

Persistence and Git

The campaign artifacts, especially research/brief.md, are the authoritative sources of scientific evidence. The Researcher must not use Git history as scientific evidence or as a routine workspace-discovery mechanism.

The Runner owns mutating Git operations, experiment code anchoring, restoration, Git-based provenance, commits and repository history management. The Researcher has read-only Git access solely for code provenance and code inspection when the current task specifically requires understanding the experiment's current code state or delta. It requests restoration through the existing keep / revert lineage contract; it does not reconstruct ancestry or select restoration commits.

research/results.jsonl is written before research/EXPERIMENTS.md is regenerated atomically. Validation-only commands do not reconcile or mutate the derived view. Researcher-owned tests and scientific code travel together in the experiment's code_changes and Git lineage.

Version-4 closure publishes every selected working or best-known candidate to research/checkpoints/retained/<campaign-id>/ before candidate cleanup and commits the artifact with the state that references it. A retained inference artifact consists of model.zip, artifact.json and policy_runtime.pkl; preprocessing state and its per-episode reset behavior are part of that saved runtime contract. Working and best-known lineages are independent Researcher designations, not Runner rankings.

An unchanged continuation restores the selected parent's complete scientific recipe and configuration before validation and training. An ordinary transfer experiment may instead combine a selected policy with the intentionally changed current science. Historical development evidence may be reused only when policy identity and evaluation settings match; whether it supports a comparison remains the Researcher's decision.