I think this is mostly a documentation bug, and the feedback I got in the Slack channel suggests this is a general problem with all of the RoomPosition documentation, but here is the issue.
Example:
Creep is on a room boundary at W2N1 @ 0,25 and computes a path to move to W2N1 @ 1,25 (e.g. move 1 tile to the RIGHT)
On the next tick, the creep has been magically teleported to W1N1 @ 49,25 and when I call creep.pos.getDirectionTo(W2N1 @ 1,25) it returns the direction LEFT instead of the expected RIGHT.
Thus the creep moves LEFT to W1N1 @ 48,25 which is completely the wrong direction.
The documentation for RoomPosition does not say anything at all about it failing to work when the 2 positions are in different rooms, and every example I have seen regarding path finding completely ignores this problem with room boundaries.
At the very least I think a big "THIS FUNCTION FAILS TO WORK IN CROSS-ROOM SITUATIONS" notice should be added to RoomPosition documentation, especially to getDirectionTo which definitely does not work.
Such a notice would likely have saved me hours of debugging.
Generally speaking the functioning of room boundaries is not discussed in any documentation and I further suggest an in depth review of it if you can get around to it.
Thanks!