How to Rename Terragrunt Project Folders Without Breaking Remote State

Terragrunt's default behavior derives remote state keys from module file paths using path_relative_to_include(), which breaks state lookups whenever a folder is renamed or moved. This forces engineers into slow, error-prone fixes like terraform state mv or terraform import just to complete a simple reorganization. A practical workaround involves adding a project.hcl file to each module with a fixed legacy_prefix value that pins the state key to its original path, independent of the folder's current location. The root configuration is then updated to read that prefix instead of deriving the key from the live file path. Before finalizing any reorganization, running terragrunt plan on every affected module and confirming zero planned changes verifies that state keys remain correctly mapped.