roadrunner-build-scenario-from-osc

# Build RoadRunner Scenario from OpenSCENARIO

Interpret an OpenSCENARIO 1.x (.xosc) file and recreate the scenario in
RoadRunner using the `roadrunner-scenario-authoring` skill. Translates positions,
maps constructs, preserves relative references, and builds correct phase logic.

## When to Use

- User has a .xosc file and wants to recreate it in RoadRunner
- User wants to programmatically build a scenario from OpenSCENARIO
- User says "build this .xosc in RoadRunner" or "recreate this scenario"
- User has an OpenSCENARIO file from a partner or standards body (e.g., Euro NCAP, ALKS)
- User wants to generate a MATLAB script from a .xosc file
- User says "convert this xosc to matlab" or "recreate with a matlab script"

## When NOT to Use

- User says "import" a .xosc file — they want `importScenario(rrApp, xoscPath)`, not this skill. Simply call the API directly.
- User wants to use RoadRunner's built-in `importScenario` (let them — it works for simple cases)
- User wants to create a scenario from scratch **without** a .xosc file (use `roadrunner-scenario-authoring`)
- User wants to export a scenario TO OpenSCENARIO (use `roadrunner-export-scenario`)

## Critical Rules

1. **Never fabricate actions or conditions not present in the source XOSC.**
   If a construct cannot be mapped, skip it and warn the user.

2. **Never propose workarounds.** Do not replace DistanceToPointCondition with
   DurationCondition, do not substitute SimulationTimeCondition for unsupported
   triggers, do not add any construct not in the source.

3. **Never simplify or duplicate trajectory vertices.** Extract exactly the
   polyline vertices present in the source XOSC — no fewer, no more. Do not
   reduce 90 vertices to 5. Do not duplicate start/end points during extraction.

4. **Never guess scenes.** Only report the .xodr filename from `<LogicFile>`.
   Import it — do not search for a scene with a similar name.

5. **Never convert relative references to absolute.** If the source uses
   `RelativeTargetSpeed delta=-8`, preserve it as `SpeedReference="actor"` with
   `Direction="slower"`, `Speed=8`. Do not compute and hardcode `7 m/s`.

6. **Never omit unsupported features silently.** Always flag them explicitly in
   the Scenario Description under "Unsupported Constructs."

7. **Describe intent, not XOSC structure.** Collapse placeholder Acts
   (MW_WaitAction) into end conditions. Do not create phases for scaffolding
   elements that have no meaningful actor actions.

## Workflow

This skill operates in two steps. Complete Step 1 first, present the description
to the user for review, then proceed to Step 2 only after approval.

---

### Step 1: Analyze the .xosc and Produce a Scenario Description

Parse the .xosc and its referenced .xodr following this strict logical order.

#### 1a. Validate the input

Read the .xosc XML. If the file is invalid XML, missing required elements, or
fails basic structural checks, **stop and report the error**. Do not guess or
assume missing data. If data is ambiguous, state the assumption explicitly.

#### 1b. Resolve parameters, expressions, and catalogs

Before interpreting any values, resolve all references:

- **ParameterDeclarations / VariableDeclarations**: Evaluate `${...}` expressions
  to concrete numeric values. Process in declaration order (later params may
  reference earlier ones).
- **CatalogReferences**: Read the referenced catalog XML file (from
  `<CatalogLocations>`), find the entry by `catalogName` + `entryName`, extract
  the vehicle/pedestrian definition (model3d path, category, bounding box).

```matlab
% Parameter expression resolution example
params.HostSpeed_kph = 80;
params.LeadTime_s = 6;
params.hostSpeed_ms = params.HostSpeed_kph / 3.6;        % 22.2222
params.leadSpeed_ms = params.hostSpeed_ms * 0.5;         % 11.1111
params.initSeparation = (params.hostSpeed_ms + params.leadSpeed_ms) * params.LeadTime_s; % 200
```

#### 1c. Describe the Init phase

For each actor's Private actions in `<Init>`:

1. **TeleportAction** — convert position to world [x, y, z]:
   - WorldPosition: use directly
   - LanePosition: translate using .xodr (see `scripts/xoscPositionToWorld.p`)
   - RoadPosition: translate using .xodr (see `scripts/xoscPositionToWorld.p`)
   - **CRITICAL: All parameters to `xoscPositionToWorld` MUST be numeric.**
     XML attributes are always strings — convert with `str2double()` before calling:
     ```matlab
     pos = xoscPositionToWorld(xodrPath, 'LanePosition', ...
         'roadId', str2double(roadId), 'laneId', str2double(laneId), ...
         's', str2double(s), 'offset', str2double(offset));
     ```
     Passing strings silently produces wrong coordinates (up to 12m error).
   - RelativeObjectPosition: rotate dx/dy by entity heading, add to base position
   - RelativeRoadPosition: inverse-lookup base entity road coords, offset s/t
   - RelativeLanePosition: inverse-lookup base lane, compute target lane + s
     (skip center lane when dLane crosses from negative to positive IDs)
   - Process entities in dependency order: resolve reference entities first

2. **Heading** — The RoadRunner API does not support setting actor orientation.
   Actors always align with road direction at their anchor point. Do NOT include
   heading in the scenario description — it cannot be applied.
   Note: The `h` attribute from XOSC is still needed for RelativeObjectPosition
   translation (to rotate dx/dy in the entity's local frame), but it is not set
   on the placed actor.

3. **SpeedAction** — record the speed value and whether it is absolute or relative.
   For relative: describe as `<abs(delta)> m/s <direction> relative to <ref actor>`
   where direction is "slower" (delta < 0), "faster" (delta > 0), or "same" (0).

4. **FollowTrajectoryAction** — supported only if effectively starts at t=0.
   This means either: (a) in Init, or (b) in Story where the trigger chain
   resolves to t=0. Resolve by tracing: if Event StartTrigger is
   `StoryboardElementStat