filesystem-path-rationalization — reorganize a project's layout without breaking it

Take a project whose files and directories drifted into inconsistency and bring it to one stated convention: decide the target shape, move files atomically, and update every reference (imports, includes, config, docs, CI) so builds, tests, and links stay green.

⚠️ Critical Constraints

• Build the reference graph BEFORE moving anything. Why: a move that updates the file but not its importers compiles locally and breaks at integration. Find every inbound reference first.
  • WRONG: git mv src/util.py src/lib/util.py then run the build and chase errors one by one.
  • CORRECT: rg -n "util" --type py (and config/docs) to enumerate referrers, record them in the move-map, then move and rewrite all referrers in one pass.