MIG-5: the reference pipeline — three sources, one downstream half

CHANGELOG.md

@@ -15,6 +15,36 @@ Current schema contract version: **1**.
 
 ### Added
 
+- **The reference pipeline: three source categories, one downstream half**
+  — `workspace_reference_pipeline`
+  ([`tests/motion/test_reference_pipeline.py`](tests/motion/test_reference_pipeline.py)).
+  This is the motion migration's cross-repository test (MIG-5) and boundary
+  consolidation's BND-1. It bakes three clips onto `Seed-san.vrm`:
+  - a `.vrma`, through this repository's importer;
+  - a BVH export, as `usd-motion-plugins`' `motion_convert` wrote it;
+  - a recorded live session, as its `motion_record` wrote it.
+
+  All three go through one `motion_retarget` argument list that differs only
+  in `--animation`. The test asserts that the downstream half is the same code,
+  in three ways:
+  - `--load-report`'s plugins and modules differ across sources by the first
+    arrow's plugin alone (`usdVrmaFileFormat` for a `.vrma`);
+  - the authored layers have one shape and one joint order;
+  - every bake passes the same checks with one tolerance. The bound bones
+    reproduce the clip's rotation away from rest and the hips its travel,
+    unbindable bones are named, nothing outside the humanoid moves, and scales
+    are authored.
+
+  Four mutations each fail at the check meant to catch them: a per-source
+  flag on the root motion, a swapped arm mapping, a first arrow that is not
+  allowed, and a renamed animation prim.
+
+  `workspace_reference_pipeline_local` runs the same checks over data that
+  cannot be committed. It reads `USDVRM_LOCAL_AVATAR` and
+  `USDVRM_LOCAL_VRMA_DIR`, can keep each bake in `USDVRM_LOCAL_OUTPUT_DIR`,
+  and reports Skipped without them. Measured on 2026-09-24 over
+  `AliciaSolid.vrm` (VRM 0.x) and the seven VRM Animation MotionPack clips,
+  with the export and the session beside them: all nine pass.
 - **A plain-CMake lane with no `ost` in it** —
   [`.github/workflows/plain-cmake.yml`](.github/workflows/plain-cmake.yml).
   On Linux it builds and tests the workspace from an OpenUSD 26.08 install

CMakeLists.txt

@@ -248,6 +248,46 @@ if(USDVRM_BUILD_TESTS AND USDVRM_TEST_PYTHON
     endif()
 endif()
 
+# The reference pipeline: a `.vrma`, a converted BVH export and a recorded
+# session through one downstream invocation onto one VRM, asserted to be the
+# same code rather than three plausible outputs (MIG-5's cross-repository test,
+# boundary consolidation BND-1). Two of the three first arrows are
+# usd-motion-plugins' tools, read as their committed output; the third is
+# usdVrmaFileFormat, so this needs both importers and the tool in one build.
+#
+# `_local` is the same test over an avatar and `.vrma` files that cannot be
+# committed, named by USDVRM_LOCAL_AVATAR and USDVRM_LOCAL_VRMA_DIR in the
+# environment of the run; without them it reports Skipped.
+if(USDVRM_BUILD_TESTS AND USDVRM_TEST_PYTHON
+   AND TARGET motion_retarget
+   AND TARGET UsdVrmFileFormat AND TARGET UsdVrmaFileFormat
+   AND EXISTS "${_real_avatar}")
+    set(_reference_plugins "${CMAKE_CURRENT_SOURCE_DIR}/plugins")
+    set(_reference_resources "${CMAKE_CURRENT_BINARY_DIR}/plugins")
+    set(_reference_common
+        "${CMAKE_CURRENT_SOURCE_DIR}/tests/motion/test_reference_pipeline.py"
+        --retarget "$<TARGET_FILE:motion_retarget>"
+        --bvh-clip "${CMAKE_CURRENT_SOURCE_DIR}/tests/motion/fixtures/mocopi-mobile-arm-raise-turn.usda"
+        --trace-clip "${CMAKE_CURRENT_SOURCE_DIR}/tools/motionRetarget/tests/fixtures/recorded_session_clip.usda")
+    add_test(NAME workspace_reference_pipeline
+        COMMAND "${USDVRM_TEST_PYTHON}" ${_reference_common}
+            --avatar "${_real_avatar}"
+            --vrma "${_reference_plugins}/usdVrmaFileFormat/tests/fixtures/canonical_walk.vrma")
+    add_test(NAME workspace_reference_pipeline_local
+        COMMAND "${USDVRM_TEST_PYTHON}" ${_reference_common} --local)
+    set_tests_properties(workspace_reference_pipeline workspace_reference_pipeline_local
+        PROPERTIES
+        ENVIRONMENT_MODIFICATION
+            "PATH=path_list_prepend:${_e2e_usd_root}/bin;PATH=path_list_prepend:${_e2e_usd_root}/lib;PATH=path_list_prepend:$<TARGET_FILE_DIR:UsdVrmFileFormat>;PATH=path_list_prepend:$<TARGET_FILE_DIR:UsdVrmaFileFormat>;PATH=path_list_prepend:${_reference_plugins}/vrmSchema/lib;PATH=path_list_prepend:$<TARGET_FILE_DIR:vrmContainer::vrmContainer>;PYTHONPATH=path_list_prepend:${_e2e_usd_root}/lib/python;PYTHONPATH=path_list_prepend:${_e2e_usd_root}/lib/site-packages;PXR_PLUGINPATH_NAME=path_list_prepend:${_reference_resources}/usdVrmFileFormat/tests/resources/usdVrmFileFormat;PXR_PLUGINPATH_NAME=path_list_prepend:${_reference_resources}/usdVrmaFileFormat/tests/resources/usdVrmaFileFormat;PXR_PLUGINPATH_NAME=path_list_prepend:${_reference_plugins}/vrmSchema/plugin/resources/vrmSchema"
+        LABELS "motion.integration;motion.real-corpus")
+    set_tests_properties(workspace_reference_pipeline_local PROPERTIES
+        SKIP_RETURN_CODE 77)
+else()
+    message(STATUS
+        "usd-vrm-plugins: a tool or a file-format bundle is not in this build "
+        "tree; skipping workspace_reference_pipeline")
+endif()
+
 # The OpenExec plan's P0-6: a `motion_retarget` bake against `execMotion` +
 # `execVrm` evaluating the same avatar and clip. Here for the same reason as the
 # two tests above -- it is a composition of both exec bundles and the retarget

docs/roadmap/boundary-consolidation.md

@@ -108,7 +108,7 @@ Generator:  request/context          -> MotionClip or a pose stream
 
 Done when a fifth producer can be added by naming which crossing it takes.
 
-## 3. BND-1 — one reference pipeline, proved once for every category ⬜
+## 3. BND-1 — one reference pipeline, proved once for every category ✅
 
 Every category reaches `UsdSkelAnimation` today, and each is proved by its own
 tests along its own path. There is no single test that says *the same thing*
@@ -118,14 +118,27 @@ happens to all of them.
 source → canonical MotionClip → vrmRetarget → UsdSkelAnimation → validation
 ```
 
-- ⬜ One integration test, three sources: a `.vrma` clip, a BVH export, and a
+- ✅ One integration test, three sources: a `.vrma` clip, a BVH export, and a
   recorded live trace — through the identical downstream call sequence, with the
   source-specific part confined to the first arrow.
-- ⬜ The assertion is that the downstream half is **the same code**, not that
+- ✅ The assertion is that the downstream half is **the same code**, not that
   three outputs are individually plausible. A source that needs a downstream
   branch has found a boundary defect, which is the point of running them
   together.
 
+**Done on 2026-09-24, as `workspace_reference_pipeline`**
+(`tests/motion/test_reference_pipeline.py`), which is also the motion
+migration's MIG-5 cross-repository test. `vrmRetarget` in the diagram above is
+now the consumed `motionRetarget` driven by `motion_retarget`. The BVH export
+and the recorded trace arrive as the clips `usd-motion-plugins`' converter and
+recorder wrote, because those first arrows are that repository's now. "The same
+code" is measured three ways:
+
+- the plugins and modules each run loads differ by the first arrow's importer
+  alone;
+- the authored layers share one shape and joint order;
+- every bake passes one set of motion checks.
+
 This is the test a fourth source is added *to*. NPZ/AMASS ships when it can join
 it without changing it.
 

docs/roadmap/current.md

@@ -209,8 +209,9 @@ Each step's record is in [the track](motion-foundation-split.md).
 - ⬜ The aggregate product installs and opens a `.vrm` and a `.vrma` from
   release artifacts, with the shared core resolved as a dependency. That is
   the next release's dry run.
-- ⬜ The cross-repository test — VRMA → `MotionClip` → a target VRM — runs by
-  default somewhere, and here until an integration repository exists.
+- ✅ The cross-repository test — VRMA → `MotionClip` → a target VRM — runs by
+  default: `workspace_reference_pipeline`, here until an integration
+  repository exists (2026-09-24).
 
 A new generic motion feature is proposed in `usd-motion-plugins`, and a new
 device or protocol input in `motion-connectors`

docs/roadmap/motion-foundation-split.md

@@ -1,6 +1,6 @@
 # Motion migration — generic motion to `usd-motion-plugins`, input to `motion-connectors`
 
-**Status:** ✅ MIG-0..MIG-4 on this side — every identity [WORKSPACE.md §9.1](../architecture/WORKSPACE.md#91-destination-of-every-identity) sends elsewhere arrived there with its history (2026-09-19..21) and is consumed or deleted here (2026-09-21..24), `execMotion` last; what MIG-4 still owes is `motion-connectors`' (recorded evidence, ARDY); 🚧 MIG-5 — the mechanical check and the reduced contract are done, the release-artifact proof and the cross-repository test are not · **Target:** after the OpenExec foundation ·
+**Status:** ✅ MIG-0..MIG-4 on this side — every identity [WORKSPACE.md §9.1](../architecture/WORKSPACE.md#91-destination-of-every-identity) sends elsewhere arrived there with its history (2026-09-19..21) and is consumed or deleted here (2026-09-21..24), `execMotion` last; what MIG-4 still owes is `motion-connectors`' (recorded evidence, ARDY); 🚧 MIG-5 — the mechanical check, the reduced contract and the cross-repository test are done; the release-artifact proof is the next release's dry run · **Target:** after the OpenExec foundation ·
 **Structure:** [architecture/WORKSPACE.md §9](../architecture/WORKSPACE.md#9-destinations-under-the-motion-architecture) ·
 **Policy:** the `usd-motion-plugins` design policy §37, and
 [design/INTEGRATION_SCOPE_POLICY.md](../design/INTEGRATION_SCOPE_POLICY.md) §13 ·
@@ -572,10 +572,22 @@ repository's, and needs nothing from this one.
     rule kept.
 - ⬜ The aggregate product still installs and opens a `.vrm` and a `.vrma`,
   with the shared core resolved as a dependency, from release artifacts.
-- ⬜ The cross-repository test — VRMA → `MotionClip` → a target VRM — runs
+- ✅ The cross-repository test — VRMA → `MotionClip` → a target VRM — runs
   somewhere by default. The motion-plugins policy puts such tests in a runtime
   or integration repository (its §30.6); until one exists it stays here,
   because this repository is its natural integrator.
+  - It is `workspace_reference_pipeline` (2026-09-24), which is also boundary
+    consolidation's BND-1. It bakes three categories onto `Seed-san.vrm`
+    through one `motion_retarget` argument list: a `.vrma` through this
+    repository's importer, and a BVH export and a recorded session as
+    `motion_convert` and `motion_record` wrote them.
+  - It asserts that the half after the clip is one code path. The loaded
+    plugins and modules differ by the first arrow's importer alone, the
+    output layers share one shape, and each bake passes the same motion
+    checks.
+  - `workspace_reference_pipeline_local` repeats it over data that cannot be
+    committed, and is skipped without it. It passed over `AliciaSolid.vrm`
+    (VRM 0.x) and the seven VRM Animation MotionPack clips on 2026-09-24.
 
 ## 8. Open questions