principle-make-operations-idempotent

Make a command idempotent by designing it to converge to the same end state regardless of prior partial runs. Scan for existing state at startup, clean stale artifacts by content equivalence, and add reconciliation steps wherever leftover state could change the outcome.

Ask three questions: what happens if it runs twice in a row, what happens if the previous run crashed at every possible point, and does re-execution converge to the same end state. If any answer depends on leftover state, add a reconciliation step.

Use PID-based stale lock detection. When acquiring a lock, check whether the process ID recorded in the lock file is still alive; if not, the lock is stale and can be safely reclaimed instead of blocking the new run.

Restart-dependent behavior means partial state from the previous run is changing the next run's outcome. Fix it with convergent startup that scans existing state, adopts live sessions, and regenerates fresh input after each cycle.

Compare by content equivalence whenever cleanup or deduplication decisions depend on which artifacts are stale. Creation order is unreliable after crashes and retries, while content comparison identifies true duplicates and leftovers deterministically.