przygody-pana-cegly/docs/adr/0003-only-first-clear-commits.md

Only a First Clear commits an Attempt

The game is moving from a purely sequential campaign to one where completionists can select and replay levels they have already beaten. Coins and skills bank only on a First Clear — the first completion of a Level within a Playthrough — while a Replay records Best Time, achievements and statistics to the Profile and discards the Attempt. We chose this over committing on every completion because grinding the easiest level would otherwise be the optimal way to buy every skill.

Consequences

• A Replay must never advance campaign position. Sharing one code path between First Clear and Replay without an explicit branch is the obvious way to reintroduce this bug.
• ClearedLevels answers "is this a First Clear?" for free, since it already deduplicates.
• Coins found during a Replay are lost on completion, not just on death. This is intentional and worth surfacing in the UI.