sim/mujoco: replace string-concat MJCFBuilder with mujoco.MjSpec AST [umbrella]

[cagataycali]

Umbrella issue tracking the MJCF AST refactor documented in IDEA.md at repo root.

TL;DR

mujoco.MjSpec is the official editable MJCF AST shipped with MuJoCo 3.2+. We currently build MJCF by string-concatenating f-strings (mjcf_builder.py) and mutate scenes by round-tripping XML through xml.etree.ElementTree (~600 lines of helpers in scene_ops.py). Switching to MjSpec deletes most of that, kills several bug classes (camera orientation, keyframe-dim mismatch, mesh-path patching), and unlocks two new capabilities:

1. Agent-authored raw MJCF - validated by actually compiling it, with a clean fallback path.
2. Fine-grained live mutation - add/remove/modify bodies, geoms, sensors, tendons, equality constraints without a tmpdir + regex round-trip.

Staged plan (one PR per stage)

• Stage 0 + 1 + 2 - MjSpec builder alongside legacy, feature-flagged. Done in commit ad1d298 on feat/mjspec-refactor.
• Stage 3 - single-robot attach via spec.attach(robot_spec, prefix=..., frame=...). Replaces parts of scene_ops.inject_robot_into_scene.
• Stage 4 - multi-robot compose via repeated attach(). Deletes _prefix_robot_names, _namespace_robot_default_classes, compose_multi_robot_scene.
• Stage 5 - port scene_ops.inject_* / eject_* to spec.recompile(model, data). Handles keyframe-dim mismatch natively.
• Stage 6 - expose replace_scene_mjcf(xml) and patch_scene_mjcf(ops) as AgentTool actions. New capability: agent-authored raw MJCF including elements SimObject can't express (<tendon>, <equality>, <pair>, custom friction/solref, etc.).
• Stage 7 - remove feature flag, delete mjcf_builder.py, audit scene_ops.py (should shrink from ~980 to <500 lines).

Success criteria

• mjcf_builder.py deleted.
• scene_ops.py under 500 lines.
• All existing tests pass.
• One integration test proves an agent can author raw MJCF with a <tendon> or <equality> element (unexpressible via SimObject).
• No test asserts on exact XML strings.
• grep -r "f'<" strands_robots/simulation/mujoco/ returns nothing.

Risks (from IDEA.md)

1. recompile(model, data) preserves qpos only when joint dims unchanged. Adding a freejoint changes nqpos. Mitigated per-stage as we port the inject path.
2. spec.to_xml() is canonical, not byte-identical to input. Any test asserting exact XML strings is wrong and should be rewritten against compiled model properties.
3. attach() default-class naming differs from current _namespace_robot_default_classes. Concrete test needed with 2 robots from different URDFs.
4. MuJoCo compiler errors are C-level and sometimes cryptic. Wrap spec.compile() with context about which op was being applied.

Coordination

• Stages 0-4 are mostly additive and land safely alongside PR feat: MuJoCo simulation backend - AgentTool with 35 actions #85.
• Stage 5 touches scene_ops and should coordinate with open PR feat: MuJoCo simulation backend - AgentTool with 35 actions #85 changes.
• Full plan + pseudocode in IDEA.md at repo root.

[cagataycali]

Umbrella complete. All 7 stages of IDEA.md delivered in PR #85.

Summary

Stages 0-7 all done:

• sim/mujoco: MjSpec stage 3 - single-robot attach via spec.attach() (#121) #122 ✅ Stage 3: single-robot attach via spec.attach()
• sim/mujoco: MjSpec stage 4 - multi-robot compose via repeated attach() (#121) #123 ✅ Stage 4: multi-robot compose via repeated attach()
• sim/mujoco: MjSpec stage 5 - port scene_ops inject_/eject_ to spec.recompile() (#121) #124 ✅ Stage 5: scene_ops inject/eject via spec.recompile()
• sim/mujoco: MjSpec stage 6 - agent-authored raw MJCF (replace_scene_mjcf / patch_scene_mjcf) (#121) #125 ✅ Stage 6: replace_scene_mjcf + patch_scene_mjcf agent escape hatches
• sim/mujoco: MjSpec stage 7 - remove feature flag, delete mjcf_builder.py (#121) #126 ✅ Stage 7: feature flag removed, mjcf_builder.py deleted

Numbers vs. IDEA.md success criteria

Criterion	Target	Actual
mjcf_builder.py deleted	yes	✅
scene_ops.py under 500 lines	<500	481
All tests pass	green	428 passed, 1 skipped
<tendon> integration test	present	test_replace_scene_mjcf.py::test_replace_with_tendon_element
No tests assert on exact XML	none	✅ rewritten to assert on MjModel / MjsBody structure
grep -r "f'<" strands_robots/simulation/mujoco/	empty	✅

Delivered commits

• ad1d298 feat(sim/mujoco): MjSpec-based builder (stages 0-2 of IDEA.md)
• c2e8826 feat(sim/mujoco): finish MjSpec refactor (stages 3-7 of IDEA.md)
• 3404809 feat(sim/mujoco): add patch_scene_mjcf structured-op MJCF mutator