Flush before you retire the source

Flush the evidence before you retire the source, not after.

Migrating state out of a project directory is mostly ordinary file work, and there is exactly one dangerous instant: the new copy is verified and the old one is about to stop being authoritative.

If the receipt describing what was migrated is still sitting in a write buffer when the originals are retired, a crash in that window leaves a machine that has lost its source and cannot prove what replaced it. Not corrupted — unexplainable, which is worse to be handed.

So the order is: write the destination and sync it, write the verified backup and sync it, flush the migration evidence, and only then retire the source. Interrupted anywhere above that last step, both copies still exist. Messy, and recoverable.

And when the flush itself fails, it does not push on. It reports the failure and preserves both the published copies and the retired originals. Two copies and a clear error beats one copy and a clean exit.

The rule generalises to anything that removes an original: the record of what you did must be durable before the thing it describes is gone.