docs: progression CONTEXT, ADRs 0001-0004, phase A plan

ignore .idea/ .superpowers/ bin/ obj/; drop 3 identical csproj backups

CONTEXT.md

@@ -0,0 +1,91 @@
+# Mr. Brick Adventures
+
+A 2D platformer. This context covers **player state and progression** — what the player has, what they have done,
+and at what point each of those becomes permanent. Gameplay behaviour (movement, combat, hazards) lives in the
+composable components and is deliberately outside this context.
+
+## Language
+
+### Scopes
+
+Three lifetimes. Every fact in this context belongs to exactly one.
+
+**Attempt**:
+One try at a level, from entering it to either completing it or losing a life. Holds a ledger of everything that
+happened during the try — coins found, coins spent, skills bought. Discarded whole if the player dies.
+_Avoid_: Session, run, life
+
+**Playthrough**:
+One game from New Game until game over, identified by a `PlaythroughId`. Holds lives, banked coins, owned skills
+and their levels, campaign position, and which levels it has cleared. Several exist at once and the player picks
+between them.
+_Avoid_: Save, save slot, progress, game, run
+
+**Profile**:
+Everything shared across all Playthroughs, one per installation. Achievements, best time per Level, and lifetime
+statistics. Never reset by starting a new Playthrough.
+_Avoid_: Global state, meta, persistent data, account
+
+### Operations
+
+**Commit**:
+Applying an Attempt's ledger to the Playthrough. Only a First Clear commits — nothing else, ever.
+_Avoid_: Save, persist, flush, sync
+
+**First Clear**:
+Completing a Level this Playthrough has not cleared before. The only event that commits an Attempt and advances
+campaign position.
+_Avoid_: Level complete, finish (both ambiguous — they also describe a Replay)
+
+**Replay**:
+Completing a Level this Playthrough has already cleared. Records Best Time, achievements and statistics to the
+Profile; commits nothing and never advances campaign position.
+_Avoid_: Practice, retry, second run
+
+**Bank**:
+The coins a Playthrough holds, as opposed to coins found in the current Attempt. Coins are banked by committing,
+never on pickup.
+_Avoid_: Total coins, saved coins
+
+**Discard**:
+Throwing away an Attempt's ledger — on death, or at the end of a Replay. Purchases made during the Attempt are
+undone by discarding, not refunded; under the ledger they never happened.
+_Avoid_: Reset, rollback, revert
+
+### Things
+
+**Level**:
+One playable stage, identified by a stable `LevelId` — never by position in a list. Knows its scene and display
+name. Ids must survive inserting and reordering levels, because Playthroughs and Best Times both reference them.
+_Avoid_: Stage, scene, level index
+
+**Cleared Levels**:
+The Levels a Playthrough has completed at least once. Gates both campaign progression and level select; whether a
+Level is reachable is computed from this, never stored alongside it.
+_Avoid_: Unlocked levels, completed levels, available levels
+
+**Skill**:
+An ability the player can own and upgrade. `SkillData` is the authored asset describing one (name, icon, upgrade
+table) and is immutable at runtime; the level the player has reached in it belongs to the Playthrough.
+_Avoid_: Ability, power-up, upgrade (for the skill itself)
+
+**Movement Ability**:
+A composable behaviour attached to the player controller (jump, wall-jump, gravity). Unrelated to Skill —
+authored per movement preset, not owned, not upgraded, not persisted.
+_Avoid_: Skill, movement skill
+
+**Best Time**:
+The fastest recorded completion of a Level, from a First Clear or a Replay alike. Belongs to the Profile, so it
+survives New Game and is shared by every Playthrough. Stored alongside, but distinct from, the ghost replay
+frames that produced it.
+_Avoid_: Personal best, high score, record
+
+## Rules
+
+- Reads may cross scopes freely — affordability spans Attempt and Playthrough. Writes must not.
+- Derived facts are computed, never stored. Level reachability is derived from Cleared Levels; total coins from
+  Attempt plus Bank. Storing either alongside its source creates the second source of truth this context exists
+  to prevent.
+- Achievements are mirrored to Steam, which is per-account and cannot be un-earned. That is why they are Profile
+  and not Playthrough: a per-Playthrough achievement list would contradict Steam permanently.
+- Nothing in this context may reference Godot. Its correctness must be checkable without a scene tree.