That sort of makes sense, although I'd prefer it to not care about the layer #; seems silly that it can't go down a layer.
Sources are open and you more than welcome to make them better and clever
I do have one more situation that doesn't make sense to me: If I set the layer to 2, and then I set the layer to 5 (I just modified layer 2 slightly to have FN5 on it), I would expect transparent keys on 5 to reflect the keys from layer 2, but instead, the transparent keys reflect layer 0.
This is because you use ACTION_LAYER_SET.
Try to use ACTION_LAYER_ON/ACTION_LAYER_OFF instead.
I can work around these oddities as you mentioned, I'm just trying to make sense of it. It's different than how Ben's firmware works, and between you and me, I like the logic his uses for layers more than TMK thus far
The difference is simple.
Ben's fw use real stack structure under the hood, while TMK use bit vector of active layers.
So, when you activate layers 2, 1, 3 (in that order), then Ben's fw will look at layer 3, then (if TRNS) 1, then 2, then 0.
In same situation TMK will just mark layers 0, 1, 2 and 3 as active, and as stated in doc/keymap.md - "***higher layer has higher priority on stack of layers***".
In your example (L2 then L5): Ben's fw will have [L0, L2, L5] in stack, and TMK will have only L0 and L5 bits set. This is so because L0 is always active, and ACTION_LAYER_SET will clear all other layer bits before set what you asked. If you'll use ACTION_LAYER_ON instead, you'll get L0, L2 and L5 bits set, because ACTION_LAYER_ON will NOT clear bits for all other layers. But then don't forget to put ACTION_LAYER_OFF somewhere
Once more again - please, read doc/keymap.md carefully, in will answer to (almost) all your questions.
And once more again - try to simplify your layers, this will solve (almost) all your problems.
And after all, simpler layers are simpler to learn/remember and use.