I'm also experienced embarkment/disembarkment behavior completely different from what described in game or elsewhere, but consistent with what you describe. Totally no info on this in google, so I researched this myself and after few hours looks like I understand actual rules:
Short version:
1. Before embarkment/disembarkment current available movement points capped by lowest of unit land and sea maximum movement limit, then movement cost is deducted from available movement points.
2. Embarkment/disembarkment penalty is +2 extra movement cost on top of usual movement cost.
3. Embarkment penalty avoided by embarking from district or wonder to harbor.
4. Disembarkment penalty avoided by disembarking from friendly tile.
5. Cliffs are unbreakable barrier to embarking and disembarking, no harbor or districts can help with this.
Long version:
1. When embarking units usually receive more max movement, so this does not affect their current available movement. Better test it for case when unit is faster on land than at the sea.
Example I: 5/5 land movement -> 5/7 sea movement before embarking.
Example II: 4/5 land movement -> 4/7 sea movement before embarking.
Example III: 4/5 land movement -> ?/3 sea movement. This case shoud be tested. I'm assuming it will be 3/3.
2. When disembarking units usually receive less max movement and their actual movement are capped at their land movement before disembarking. Hence embarked unit has some "free" sea movement before disembarking that will be lost if unused before disembarking.<br>
Example I : 7/7 sea movement -> 5/5 land movement before disembarking.
Example II : 5/7 sea movement -> 5/5 land movement before disembarking.
Example III : 4/7 sea movement -> 4/5 land movement before disembarking.
3. Embarkment penalty is 2 movement points on top of normal 1 sea movement cost, so total is 3 points.
Example I: 5/5 land movement -> 5/7 sea movement before embarking -> 2/7 sea movement after embarking.
Example II: 2/5 land movement -> 2/7 sea movement before embarking -> no embarking possible.
Example III: 2/2 land movement -> 2/7 sea movement before embarking -> 0/7 sea movement after embarking.
4. Disembarkment penalty is 2 movement points on top of normal land movement cost. So total is 3 or more.
Example I: 7/7 sea movement -> 5/5 land movement before disembarking -> 2/7 after disembarking on flat terrain.
Example II: 7/7 sea movement -> 5/5 land movement before disembarking -> 0/7 after disembarking on forest hill terrain.
Example II: 2/7 sea movement -> 2/5 land movement before disembarking -> no disembarking possible.
5. Embarkment 2 movement points penalty do not applied only when embarking from completed district or wonder to harbor (even incomplete).
6. Disembarkment 2 movement points penalty do not applied when disembarking from friendly territory. Disregarding land tile owner.
7. Harbors on cliffs do not allow embarking or disembarking no matter what.
Thanks to Firaxis that to play their game you first need to exercise your brain doing such "researches". Checked on version 1.0.11.16 (Portugal), but I bet not only this version is affected. I also bet this would never be fixed.
