Refactor: scheduler: best practices for promotion_order()

Rename promotion_order() to sort_promotable_instances() for readability,
add a doxygen block, drop a redundant argument, and improve variable names,
log messages, comments, and formatting.