# Development Plan

Working document for Naked Desire implementation. Tracks current state vs. the GDD (README.md) and the phased roadmap. Update this file as state changes — code is the source of truth, this file is the navigation chart.

When the GDD changes, update README.md first, then revisit this plan. When this plan changes, keep phase exit criteria concrete so we know when to move on.

---

## 1. Implementation status snapshot

State of the C++ module as of the latest pass. File references use `Source/NakedDesire/...` paths.

### 1.1 Implemented

- **Item identity scaffold (GDD §6.1)** — `Items/ItemInstance.h` defines `UItemInstance` as an abstract `UObject` with a stable `FGuid InstanceID`, auto-assigned in `PostInitProperties` and refreshed in `PostDuplicate`. `Clothing/ClothingItemInstance.h` inherits from it and holds per-instance `Condition`, a pointer to the immutable `UClothingItem` definition, and a `StoredItems` array for container slots.
- **Definition / instance split (GDD §6.1, §17.4)** — `Clothing/ClothingItem.h` is the immutable `UPrimaryDataAsset` definition. Most fields align with the current GDD: `Coverage`, `CanExpose`, `ContainerSlots` (typed S/M/L via `EGarmentContainerSlotType` + `FGarmentContainerSlot`), `ProgressionPath`, plus rendering data (`SkeletalMesh`, `Materials`, `StaticMesh`). The `IsUnderwear` and `IsRestrictive` fields also exist but **no longer match the locked spec** (§20 #20, §20 #21) — see §1.4 for the removal / migration work.
- **Progression path enum (GDD §5)** — `Progression/ProgressionPath.h` defines `EProgressionPath { None, Slut, Exhibitionist, Slave }`. Used on `UClothingItem::ProgressionPath`.
- **Body-part enum (GDD §6.3)** — `Clothing/BodyPart.h` defines `EBodyPart { None, Boobs, Ass, Genitals }`. Used on `UClothingItem::CanExpose`.
- **Save scaffolding (GDD §16)** — `SaveGame/SaveSubsystem.h/.cpp` (`UGameInstanceSubsystem`), `SaveGame/ItemSaveRecord.h` (generic `{ InstanceId, Definition, Condition, ParentId }`). `Global/Constants.h` now uses `DefaultSaveSlotName` instead of a single `SLOT_NAME` macro.
- **Observation-driven embarrassment (GDD §7.1)** — `NPC/NPCAIController.cpp:56-69` listens to `OnTargetPerceptionUpdated` and forwards bSensed transitions to `Stats/StatsManager::SetObserved`. `Stats/StatsManager::TickComponent` (`StatsManager.cpp:23-38`) now gates gain vs. decay on `ObserverCount` instead of unconditional decay. Foundation for Phase 4.
- **Modular character w/ per-slot meshes** — `Player/NakedDesireCharacter.cpp:40-67` creates 14 skeletal mesh components, one per current `EClothingSlotType` value. Aligns with GDD §17.6 in spirit; the specific slot list needs reshaping per §1.4 (locked 18-slot list now lives in GDD §6.5).
- **Equip / unequip / drop event** — `Clothing/ClothingManager.cpp:88-163` (slot-based, broadcasts `OnClothingEquip / Unequip / Dropped` with `UClothingItemInstance*`).
- **Censorship toggle** — compliance feature on `NakedDesireCharacter` (`BoobL/R`, `Front/BackBottom` static meshes), driven by `UNakedDesireUserSettings`.
- **AI sight + behavior tree** — `NPC/NPCAIController.cpp` runs a BT with `Player` / `TargetLocation` / `SpawnLocation` blackboard keys. `NPC/NPCSpawner.cpp` proximity-gated spawn with day / night caps.
- **Mission framework** — `Mission` → `MissionGoal` → `GoalRestriction` composition (`MissionBuilder/`). Two goals (`FlashGoal`, `MinTimeGoal`), three restrictions (`EquipClothing`, `ExposeBodyPart`, `Location`). Iterate-and-mutate bug in `MissionsManager::RefreshDailyMissions` resolved (`MissionsManager.cpp:53-68`).
- **Daily-mission OOB guarded** — `NakedDesireGameMode::RefreshDailyMissions` now clamps `DaysPassed` to the authored array bounds (`NakedDesireGameMode.cpp:70-71`). Still a hand-authored list (see §1.3).
- **Location triggers** — `Locations/LocationTrigger`, `Locations/LocationData` via gameplay tags (GDD §10.4 area foundation). `ALocationTrigger` now carries a `bIsApartment` flag; when set, its box overlap drives session start / end on the session subsystem.
- **Session manager (GDD §4.1–§4.4)** — `Global/SessionManagerSubsystem.h/.cpp` (`UWorldSubsystem`). Tracks `bSessionActive`, emits `OnSessionStart` / `OnSessionEnd(ESessionLossCause)`; `ESessionLossCause = { SafeReturn, EmbarrassmentMax, EnergyZero, PoliceCapture }`. Apartment `ALocationTrigger` starts a session on exit and safely ends it on re-entry. Subscribes (next-tick after world begin play) to `UStatsManager::EmbarrassmentUpdate` (max-hit → `EmbarrassmentMax`) and `EnergyUpdate` (≤0 → `EnergyZero`). Exposes `bPoliceChaseActive` (+ setter / getter) for the §4.4 loss-precedence rule the resolver owns. Replaces the old `EndGameEmbarrassed` GameMode BP call, which `UStatsManager::IncreaseEmbarrassment` no longer invokes. The `EndGameEmbarrassed` BlueprintImplementableEvent declaration still exists on `ANakedDesireGameMode` but is now dead from C++ and should be removed once BP no longer references it.
- **Session loss resolver (GDD §4.4)** — `Global/SessionLossResolver.h/.cpp` (`UWorldSubsystem`). Single entry point `ResolveLoss(ESessionLossCause)`, bound to `USessionManagerSubsystem::OnSessionEnd`. Applies the police-chase precedence override (any cause → `PoliceCapture` while `bPoliceChaseActive`), then per cause: `EmbarrassmentMax` no-cost; `EnergyZero` destroys every world `AItemPickup` + clears its save record (guaranteed sleep loss); `PoliceCapture` deducts `PoliceCaptureMoneyPenalty` if affordable else flags a holding-cell outcome; `SafeReturn` no loss. Never strips equipped clothing. Autosaves, then broadcasts `OnSessionLossResolved(FinalCause, bWentToHoldingCell)` for the BP presentation / time-skip layer. See §1.3 for the pieces still delegated to BP / later phases.
- **Movement** — `EnhancedInput`, walk / run / crouch (`NakedDesireCharacter.cpp:115-127`), stamina-gated run (`Tick` lines 91-113).
- **Wardrobe interactable** — `Interactables/Wardrobe.h` holds `TArray<TObjectPtr<UClothingItemInstance>> ClothingItems`; `NakedDesireGameMode::BuyItem` charges money and pushes into the wardrobe.

### 1.2 Partially implemented (deviates from GDD)

- **Save subsystem (GDD §16)** — scaffolded but **not actually wired through gameplay**. `USaveSubsystem::SaveGame` (`SaveSubsystem.cpp:10-13`) delegates to `UGlobalSaveGameData::SaveGame`, which creates a *fresh empty* `UGlobalSaveGameData` (`GlobalSaveGameData.cpp:45-53`) and writes it — i.e., it does not capture the live player / wardrobe / world state at all. `USaveSubsystem::LoadGame` calls the static loader but discards the result without applying it (`SaveSubsystem.cpp:5-8`). `ClothingManager::HydrateClothing` (`ClothingManager.cpp:66-73`) is an empty stub with the previous logic commented out. Exit criterion of Phase 1 (round-trip an item with modified condition) is not met yet.
- **Item identity → world (§6.1)** — `UItemInstance` GUIDs exist, but no item has been promoted to a world `AActor`. `ClothingManager::DropClothing` (`ClothingManager.cpp:156-163`) still only broadcasts `OnClothingDropped` — no spawn, no parent reassignment in any registry.
- **Attributes (§7)** — `StatsManager` covers Embarrassment, Energy, Stamina with observation-driven gain now correctly tied to NPC perception. Missing: Lust, Pulse (§7.5), Recognition, Reputation, Followers, Wanted. Coverage weighting in the gain formula is stubbed at `0.0f` with a TODO marker (`StatsManager.cpp:30-32`). Food-buff hookpoints (per-rate multipliers for stamina regen, embarrassment-gain resistance, lust-gain resistance — see GDD §6.7) are not in place; future Phase 10 work depends on the attribute simulation accepting external multipliers cleanly.
- **Coverage (§6.3.2)** — `UClothingItem::Coverage` exists; `ClothingManager::IsBodyTypeExposed` (`ClothingManager.cpp:14-25`) is still binary. No `GetEffectiveCoverage(EBodyPart)` function. **The locked formula is now `max(coverage)` across garments covering a body part** — not sum, and no underwear halving (§20 #20). `UClothingItem::IsUnderwear` is dead spec and should be removed during the Phase 1 cleanup.
- **Body-part enums — duplicated** — both `Player/PrivateBodyPartType.h` (`EPrivateBodyPartType { FrontBottom, BackBottom, FrontTop }`) and `Clothing/BodyPart.h` (`EBodyPart { Boobs, Ass, Genitals }`) exist. `UClothingItem::CoveredBodyParts` uses the **old** enum; `UClothingItem::CanExpose` uses the **new** one. Half-migrated.
- **Mission system** — composable goals work but lacks the typed objective steps from §13.4 (`BeFullyNaked`, `BeFullyNakedNearNPCs`, `WalkNakedDistance`, `MoveDistanceFromClothing`, `BeObservedByNPCType`, `TakePhotoAtLocation`, `DeliverItemTo`). Missions still hand-authored in `MissionsConfig::DailyMissions` keyed by day index — no procedural generation, no Accept lifecycle (§13.1 / §13.2), no path-filtering on the generator (§13.4).
- **Day / night** — `NPCSpawner.cpp:38-41` reads `GetCurrentTime().Hours` and gates spawn cap, but does not affect embarrassment gain, NPC type weighting, or police spawning (see §1.3).

### 1.3 Missing

- **Session loss — remaining (GDD §4.4)** — the transactional resolver exists (`USessionLossResolver`, see §1.1), but several outcomes depend on systems not yet built: the energy-zero trudge-home cutscene, the holding-cell cutscene, the fade/teleport-to-apartment, and the time skips (one sleep cycle / fast-forward to next morning) are all delegated to BP via `OnSessionLossResolved` and not yet authored. Bag-placed-in-world loss is a TODO (bags absent, §6.4). `ClearWanted()` is a stub (no Wanted attribute until Phase 4/6, §7.7). Apartment-interior detection for loose-item loss is approximated (all `AItemPickup`s treated as "outside").
- **Three progression paths runtime (§5)** — enum exists; no XP pool, no per-path level derived from investment, no path-gated unlocks at runtime, no level-up flow. **XP is a single shared pool, not per-path** (GDD §5, §7.10).
- **Phone (§9)** — entire system absent: camera, gallery, livestream, bank, Feetex, maps, health tracker. Includes the new sub-systems:
    - **Battery (§9.8)** — passive base + per-app multiplier drain; apartment charger; portable powerbank consumable (Convenience Store); hard shutdown at 0%; mid-livestream cutoff with earnings-to-date deposited; sleep always charges to 100%.
    - **Livestream tip requests (§9.1.1)** — viewer-driven action requests with phone popup (Accept / Decline + countdown); fail = viewer count drops, no rep hit.
    - **Livestream follower trickle (§9.1.1)** — `streamQualityScore` ticks through `FollowerGainCalculator` per tick.
    - **Bank app income breakdown (§9.4)** — line items by source incl. the weekly follower auto-deposit at week boundary.
- **`PhoneSubsystem` (§17.1)** — tickable subsystem owning phone state (battery %, active app, livestream session lifecycle, charger interaction). Does not yet exist.
- **Forum (§13)** — no `UCommissionTemplate`, no procedural generation, no weekly missions distinct from daily, no profile (incl. weekly follower-income summary), no posting photos. Forum scope is locked minimal (board + own profile only, no threads / no other-users feed) — that's a non-build, but worth recording.
- **Photo & livestream** — absent.
- **NPC types (§10.2)** — only one generic `ANPC` class. No Walker / Stalker / Blogger / Snitch / Harasser, no Police, no Wanted-poster mechanic.
- **Calendar, rent, sleep (§2.4, §15.2)** — `DaysPassed` increments in `NakedDesireGameMode::OnHourChanged(4)`, but no week, no rent, no eviction, no sleep action, no apartment bed interaction.
- **Item-world AActor (§6.1)** — no `AItemActor` / `AClothingPickup` base.
- **Bag inventory (§6.4)** — absent.
- **Theft (§6.3.4)** — new chance-based model (per-tick `P_theft` after grace period) not implemented. No theft timer / probability code at all.
- **Rip & tear (§6.3.5)** — absent. `UClothingItemInstance::Condition` is read-only in code; no decrement source.
- **Expose action (§6.3.6)** — `CanExpose` data exists on the definition; runtime action absent.
- **Restrictions system (§6.3.7 / §10.4.1)** — `IsRestrictive` boolean exists on `UClothingItem` but is now stale spec. The locked design is a **per-item `restrictions` list** with granular entries (`BlockRun`, `BlockCrouch`, `BlockPhoneUse`, `BlockItemPickup`, `BlockMasturbate`, `BlockExposeAction`, and parameterized `BlockSlotChange(slot)`). No code enforcement of any restriction flag; no Key-based unlock flow; no DBD-style unlock minigame (§10.4.1).
- **Bodysuit exclusion rule (§6.5)** — when implementing the new slot enum, `ClothingManager` must auto-unequip `Top`/`Bottom`/`UnderwearTop`/`UnderwearBottom` on bodysuit equip, and vice versa.
- **Toy slots (§6.5)** — `Nipples`, `Anal`, `Vagina` are now **toy slots** (not body-clothing slots, not body-parts conflict). Independent; all three can be active. Items in these slots are sex toys from the Adult Shop (§10.4), follow standard item-identity rules, do **not** contribute to coverage, and may modify lust / embarrassment / pulse plus add audible vibration NPCs may detect.
- **Adult shop, gym, beauty salon, café, convenience store** — none.
- **Food / consumables (§6.7)** — absent. Vocabulary now locked: 2 instant effects (energy restore, lust decrease), 4 timed buffs (stamina regen +, max stamina +, embarrassment-gain resistance, lust-gain resistance). Stacking: different types parallel; same type additive up to per-type cap. Cooking minigames (slice / stir / cook) modulate buff strength; never poison.
- **Recognition, wanted state, news (§7.6–§7.7, §11.1)** — absent. Face-cover bypass via `Face` and `Eyes` slots is part of this work.
- **Underwear selling (§15.1)** — absent. Backed by the `DeliverItemTo` typed objective (player-owned source only, §13.4).
- **Endless mode flag (§3.3)** — absent.
- **Pulse attribute (§7.5)** — absent (new in the updated GDD).
- **Hunger / max-energy decay (§7.3)** — absent. The new model has two layers of max energy: **base max** (gym progression) and **effective max** (decays via hunger). Eating any food restores effective max to base max as a universal built-in effect. Sleep does **not** clear hunger. `StatsManager` currently has only `MaxEnergy = 1000.0f` (`StatsManager.h:20`) — no hunger field, no decay tick, no eat-restores-hunger hook.
- **Police chase loss precedence (§4.4)** — when a chase is active and another loss fires, capture wins. No code logic for this yet (no chase exists, no precedence resolution in the loss path).
- **Holding-cell cutscene (§4.4)** — short non-interactive cutscene played when police capture and player can't pay. Time fast-forwards to next morning. Replaces the earlier "skip days proportional to debt" prose. Absent in code (no capture path exists yet).
- **Casino (§10.4.2)** — entire new location. Main floor (slots, blackjack, roulette), VIP room with per-day entrance fee, strip-game variants of blackjack and roulette that bet clothing items, lost-and-found inventory that retains `UItemInstance` identity for lost garments, mixed pacing (slots instant; table games burn in-game minutes), no poker. Significant scope: 3 minigames + VIP gating + strip-bet flow + lost-and-found UI.
- **Phone models + Electronics Shop (§9.9 / §10.4)** — three-tier phone (Starter / Mid / Pro) with three stat axes per tier (`camera quality`, `livestream quality`, `battery capacity`). New Electronics Shop location sells Mid and Pro. **Player can own multiple phones simultaneously**; only the equipped phone is active. Battery is per-phone-instance; hot-swap at the apartment wardrobe. Profile-side state (gallery, followers, history) does not move when swapping phones.
- **Restraint unlock minigame (§10.4.1)** — DBD-style skill checks. Successful hits speed up removal; misses have no penalty; no fail state. Restraint always comes off when the baseline timer expires. Absent (no restraint flow exists).
- **Instant commission rewards (§13.1 / §13.2 / §3.1 / §4.3)** — money / XP / followers credit at the moment of commission completion, not on return home. `UMissionsManager::CollectRewards` (`MissionsManager.cpp:35-51`) currently batches rewards into a manual "collect" call — this needs to be replaced with immediate crediting on `OnMissionCompleted`.
- **Hiding spots for ground items (§6.3.4)** — new bullet in the GDD that adds a hiding-spot concept; collides with the §4.4 "sleep = guaranteed loss" rule. Spec needs clarification before code (see Working notes).
- **GAS adoption (§17.2)** — `StatsManager` is still a bespoke `UActorComponent`; no `UAttributeSet`, no `GameplayEffect`-driven modifiers.

### 1.4 Conflicts to resolve

- **`SaveGame` UPROPERTY typo** — `GlobalSaveGameData.h:35` declares `UPROPERTY(SaceGame)` instead of `SaveGame` on `DaysPassed`. The field will not serialize.
- **`USaveSubsystem::SaveGame` writes an empty save** — does not pull state from the live world before writing (`SaveSubsystem.cpp:10-13`, `GlobalSaveGameData.cpp:45-53`). Any "save" call at present destroys progress. Highest-priority correctness bug.
- **`USaveSubsystem::LoadGame` ignores the loaded object** — static returns a populated `UGlobalSaveGameData`; subsystem stores / applies nothing.
- **`EClothingSlotType` — concrete reshape to the locked 18-slot list (GDD §6.5)**

  Current enum (`Clothing/ClothingSlotType.h`, 14 values): `Nipples, Anal, Vagina, Head, Neck, Face, Eyes, Body, Top, Bottom, Bra, Panties, Socks, Shoes`.

  Target (18 slots, 4 groups): see GDD §6.5. Migration table:

  | Current      | Target            | Action                                                              |
  |--------------|-------------------|---------------------------------------------------------------------|
  | `Top`        | `Top`             | Keep                                                                |
  | `Bottom`     | `Bottom`          | Keep                                                                |
  | `Bra`        | `UnderwearTop`    | Rename                                                              |
  | `Panties`    | `UnderwearBottom` | Rename                                                              |
  | `Body`       | `Bodysuit`        | Rename + enforce exclusion with `Top`/`Bottom`/`UnderwearTop`/`UnderwearBottom` |
  | `Socks`      | `Socks`           | Keep                                                                |
  | `Shoes`      | `Footwear`        | Rename                                                              |
  | —            | `Outerwear`       | **Add**                                                             |
  | `Head`       | `Head`            | Keep                                                                |
  | `Face`       | `Face`            | Keep (now a face-cover slot per §7.6)                               |
  | `Eyes`       | `Eyes`            | Keep (now a face-cover slot per §7.6)                               |
  | `Neck`       | `Neck`            | Keep                                                                |
  | —            | `WristRestraint`  | **Add**                                                             |
  | —            | `AnkleRestraint`  | **Add**                                                             |
  | —            | `NeckRestraint`   | **Add** (distinct from cosmetic `Neck`; auto-exclusion is *not* enforced — content authoring handles visual collision) |
  | `Nipples`    | `Nipples`         | Keep — **now a toy slot, not a body-clothing slot**                 |
  | `Anal`       | `Anal`            | Keep — **now a toy slot**                                           |
  | `Vagina`     | `Vagina`          | Keep — **now a toy slot**                                           |

  Net: 14 → 18 (4 renames, 4 additions, 3 semantic repurposes). `NakedDesireCharacter::SetupClothingSlots` (`NakedDesireCharacter.cpp:357-433`) needs four new mesh components added and four existing components renamed in lockstep with BP references in `Content/Blueprints/Player`.

  Bodysuit exclusion is a runtime rule on `ClothingManager::PutOnClothing` — equipping a bodysuit must un-equip the four body slots; equipping any of those four must un-equip a present bodysuit.

  Toy slots are independent and stackable; their items are sex toys (not clothing) but use the same `UItemInstance` model. The `UClothingItem` data class is named for clothing — a `USexToyItem` (or similar) `UItemInstance` subclass may be cleaner than reusing `UClothingItem` for toys, since the toy effects (lust modifier, embarrassment modifier, pulse modifier, NPC-audible vibration) don't map onto clothing's coverage / `CanExpose` / `IsRestrictive` model.

- **Two competing body-part enums** — `EPrivateBodyPartType` vs. `EBodyPart`. `ClothingItem::CoveredBodyParts` uses one, `ClothingItem::CanExpose` uses the other. The censorship / observation code paths in `NakedDesireCharacter` and `ClothingManager` are still on `EPrivateBodyPartType`. Pick one (recommend `EBodyPart`) and migrate.
- **`UClothingList`** forward-declared in `GlobalSaveGameData.h:11`; `Wardrobe` and save records no longer use it. Dead reference; remove.
- **`Money` representation** — `ANakedDesireCharacter::Money` is `int` (`NakedDesireCharacter.h:132`); `UGlobalSaveGameData::Money` is `float` (`GlobalSaveGameData.h:27`). Pick one authoritative location and one type.
- **`STARTING_MONEY`** macro defined in `Constants.h:8` but unreferenced. Either wire it into save / character init or remove.
- **`ClothingItemInstance` has no public constructor / factory** — `ClothingItem` pointer is `protected` with no `Init(UClothingItem*)`. Wardrobe / BuyItem flows rely on `EditAnywhere Instanced` design-time population, which won't support runtime purchase or save-driven hydration.
- **`UClothingItem::IsUnderwear` is dead spec** — `ClothingItem.h:82`. The locked design (§20 #20) drops the field entirely; `coverage` is authored directly to reflect the "just underwear" discount. Remove the field and any references during Phase 1.
- **`UClothingItem::IsRestrictive` is dead spec** — `ClothingItem.h:76`. The locked design (§20 #21) replaces the boolean with a granular `restrictions` list. Remove the boolean and add a `TArray<FClothingRestriction>` (or equivalent) supporting `BlockRun`, `BlockCrouch`, `BlockPhoneUse`, `BlockItemPickup`, `BlockMasturbate`, `BlockExposeAction`, and `BlockSlotChange(slot)`. Restriction evaluation is the union across all equipped items.
- **`UClothingItem` per-body-part coverage TODO is now resolved against** — `ClothingItem.h:61` carries `// TODO: Add coverage per body part`. The locked spec uses a single `coverage` value per item (multi body parts via `covers` set + `max()` formula, §6.3.2). The TODO comment should be removed; per-body-part coverage is intentionally not the model.
- **`StatsManager::TickComponent` energy drain** — drains energy at a flat `0.9f` per tick (`StatsManager.cpp:26`) regardless of activity. GDD §7.3 specifies per-activity modifiers.
- **`NPCSpawner` day window** — uses `Hours >= 9 && < 21` for "day" (`NPCSpawner.cpp:40`); GDD §10.1 says `08:00–20:00`. Off by one hour on each end.

- **GDD shifts not yet reflected in code:**
    - **Loss resolver** must not strip equipped clothing (§4.4).
    - **Energy = 0** must trigger a "cutscene → apartment → sleep" flow, not a teleport (§4.4).
    - **Embarrassment = max** must fade to apartment with **no extra cost** (no time skip, no money penalty, no rep hit) — GDD §4.4.
    - **Police chase precedence (§4.4):** if a chase is active when any other loss fires, the loss resolves as police capture — chase wins.
    - **Police capture, can't pay (§4.4):** short non-interactive holding-cell cutscene + time skip to next morning. Replaces the earlier "skip days proportional to debt" model.
    - **Theft** is a chance-based model with grace periods and flat per-tick `P_theft`, not a ramping curve (§6.3.4).
    - **Sleep** is the deterministic side of clothing loss — guaranteed loss of every clothing item left outside the apartment (§4.4). Hiding-spots bullet in §6.3.4 currently contradicts this — see Working notes.
    - **No Helper NPC**; restraint removal is **Key + timed-unlock action with a DBD-style skill-check minigame** (§10.4.1). Successful checks speed up removal; missed checks have no penalty; restraint always comes off when the baseline timer expires.
    - **Per-item `restrictions` list** replaces `IsRestrictive` boolean (§6.3.7). Granular vocabulary: `BlockRun`, `BlockCrouch`, `BlockPhoneUse`, `BlockItemPickup`, `BlockMasturbate`, `BlockExposeAction`, parameterized `BlockSlotChange(slot)`. Restrictions union across equipped items.
    - **Coverage math** is `max()` across garments covering a body part — not sum. No underwear halving; the `IsUnderwear` flag is removed entirely (§6.3.2).
    - **Hunger / max-energy decay (§7.3):** two-layer max energy — base (gym) and effective (decays via hunger, restored by eating). Eating any food triggers the restoration as a universal built-in effect. Sleep does not clear hunger.
    - **Masturbation** is **Slut-path gated** — generator must filter `PerformAction(masturbate)` for non-Slut players; quick-action entry must hide until unlocked (§5.1 / §7.2 / §14.1). (Note: the README has a current contradiction about home-masturbation for non-Slut players — see Working notes.)
    - **Police** spawn day **and** night while `wanted` (§7.7 / §10.3).
    - **XP is a single shared pool, not per-path** — Phase 9 implementation must use a shared XP counter; a path's level is derived from how many upgrades the player has bought from that path's attribute pool (§5, §7.10).
    - **Commission lifecycle:** explicit Accept required for daily *and* weekly; un-accepted commissions carry no penalty; weekly rewards now include followers (§13.1 / §13.2). **Rewards land instantly on completion** — money / XP / followers credit at the moment the commission completes; no return-to-home "collect rewards" step. Replace the manual `UMissionsManager::CollectRewards` flow with immediate crediting on `OnMissionCompleted`.
    - **Commission generator** must respect `pathRequirement` (incl. `None` = path-neutral) and filter templates whose steps reference path-locked actions (§13.4). `failurePenalty` field is canonical; generator supplies tier-scaled default when empty.
    - **`DeliverItemTo`** must source from player inventory only; commission does not auto-issue items. Worn-underwear sales (§15.1) are the canonical use case (§13.4).
    - **Livestream → follower trickle** via `FollowerGainCalculator` per tick; signed by reputation. Tip requests give an additional bonus on completion (§9.1.1 / §13.5).
    - **Phone models (§9.9):** three tiers with three stat axes each (camera quality, livestream quality, battery capacity). Bought at the new Electronics Shop. Player may own multiple phones; gallery / followers / stats live on the profile (not the phone); battery is per-phone-instance.
    - **Casino (§10.4 / §10.4.2):** main floor (slots / blackjack / roulette, money only), VIP room (per-day entrance fee), strip-game blackjack and roulette tables in VIP that bet clothing. Lost garments go to a casino lost-and-found inventory that retains `UItemInstance` identity. Mixed pacing.
    - **Locations locked for launch:** Beach + Train Station + Casino + Electronics Shop are in; School exterior and Hot springs were cut. Vertical slice is the basic shop set only (§10.4, §18.1).
    - **Food vocabulary locked:** 2 instant effects (energy restore, lust decrease) + 4 timed buffs (stamina regen +, max stamina +, embarrassment-gain resistance, lust-gain resistance); same-type stacks additively up to a cap; never poison (§6.7). Plus the universal "eating restores effective max energy" hunger reset.

---

## 2. Architectural premise

The item-identity rule (§6.1) and the save contract (§16.3) are still load-bearing. With the definition / instance split in place, the next bottleneck is **wiring serialization through gameplay**: condition mutation, world drops, container parent links, hydration on load. Until that round-trip works, content on top of the current system has no durable home.

The session-system + loss resolver (Phase 3) is the second pin. Several GDD shifts (equipped-never-dropped, energy-zero cutscene, embarrassment-max no-extras, sleep-deterministic clothing loss) move complexity from §4.4 prose into a single deterministic resolver. Build it once, well.

GAS adoption (§17.2) remains deferred until Phase 4. Adding new attributes to the bespoke `StatsManager` in the meantime is fine — keep them additive and easy to migrate. Food buffs (§6.7) are external multipliers on attribute rates, so design the per-rate interface with that in mind even before GAS lands.

---

## 3. Phased roadmap

Phase estimates are rough and assume one engineer. Adjust as we go.

### Phase 1 — Finish item identity + save round-trip; reshape slot enum (1–2 weeks)

- Fix the `SaceGame` UPROPERTY typo on `DaysPassed` (`GlobalSaveGameData.h:35`).
- Add `UClothingItemInstance::Init(UClothingItem* Definition)` (or static factory) so instances can be constructed at runtime.
- Make `USaveSubsystem::SaveGame` actually capture live state into `UGlobalSaveGameData`: player money, equipped items, wardrobe items, calendar, observation-attribute snapshot. Populate `FItemSaveRecord` from current instances.
- Make `USaveSubsystem::LoadGame` actually apply the loaded data: rebuild instances from records, push into wardrobe + `ClothingManager` slots. Replace the commented-out `ClothingManager::HydrateClothing` with real hydration.
- Unify `EPrivateBodyPartType` and `EBodyPart` on `EBodyPart`. Migrate `ClothingItem::CoveredBodyParts`, `ClothingManager::IsBodyTypeExposed`, censorship paths in `NakedDesireCharacter`, BT / observation paths.
- **Reshape `EClothingSlotType` to the locked 18-slot list (§1.4 table).** Add `Outerwear`, `WristRestraint`, `AnkleRestraint`, `NeckRestraint`. Rename `Bra → UnderwearTop`, `Panties → UnderwearBottom`, `Body → Bodysuit`, `Shoes → Footwear`. Add four new `USkeletalMeshComponent`s in `NakedDesireCharacter` for the new slots. Update BP references in lockstep.
- **Implement Bodysuit exclusion** in `ClothingManager::PutOnClothing` (auto-unequip `Top`/`Bottom`/`UnderwearTop`/`UnderwearBottom`; vice versa).
- **Define toy items**: either a new `USexToyItem : UItemInstance` (recommended) or extend `UClothingItem` with a toy variant. Toy items target `Nipples` / `Anal` / `Vagina` slots, carry lust / embarrassment / pulse modifier fields, and an optional NPC-audible-vibration flag. Do not contribute to coverage.
- **Drop dead spec from `UClothingItem`**: remove `IsUnderwear` (`ClothingItem.h:82`) and `IsRestrictive` (`ClothingItem.h:76`); remove the `// TODO: Add coverage per body part` comment on line 61 (resolved against — single `coverage` is locked spec).
- **Replace `IsRestrictive` with a `restrictions` list** on `UClothingItem`: `TArray<FClothingRestriction>` (struct with `ERestrictionType` enum + optional `EClothingSlotType` parameter for `BlockSlotChange`). No runtime enforcement yet (Phase 4 / 10 own that) — Phase 1 just needs the data field, the struct, and the enum.
- Money: pick one authoritative location (`UGlobalSaveGameData`), make `ANakedDesireCharacter::Money` a read-through. Apply `STARTING_MONEY` at new-save creation. Reconcile int vs. float.
- Remove dead `UClothingList` forward declarations.

**Exit criteria:**
1. Item dropped at runtime, condition modified, save → quit → load reproduces the same `FGuid`, condition value, and slot / wardrobe membership.
2. `EBodyPart` is the only body-part enum in use.
3. `EClothingSlotType` matches the §6.5 18-slot list. Bodysuit exclusion is enforced at runtime. Toy slots work with at least one placeholder toy item.
4. A new game starts with `STARTING_MONEY` and rent / purchase flows debit the canonical money field.

### Phase 2 — World item actors + drop / pickup (1 week)

- `AItemActor` base wrapping a `UItemInstance*` (in `Items/`). Spawn transform, owning instance pointer, SaveGame-tagged.
- `AClothingPickup : AItemActor` with a visual representation (`UClothingItem::StaticMesh` when set, fallback to skeletal mesh impostor).
- Hook `ClothingManager::DropClothing` to spawn `AClothingPickup` at the player location with the actual instance reference — *not* a template copy. Reparent the instance from "equipped slot" to "world".
- Pickup interaction via existing `UInteractionManager` + `IInteractionTarget`. Pickup re-parents the instance into wardrobe or directly into the matching slot.
- `USaveSubsystem` extension: serialize `AClothingPickup`s as `FItemSaveRecord`s with world transform.

**Exit criteria:** unequip → world pickup actor appears → save / reload → pickup still there at the same transform with the same instance ID → pick up restores the same instance to the slot.

### Phase 3 — Session system + loss resolver (1 week)

- ~~`USessionManager` (subsystem on `UNakedDesireGameInstance` or a `UWorldSubsystem`). Apartment `ALocationTrigger` flag drives session start / end. Emits `OnSessionStart` / `OnSessionEnd` with cause.~~ **DONE (DEV-99)** — `USessionManagerSubsystem` (`UWorldSubsystem`, `Global/`). See §1.1.
- ~~`USessionLossResolver` — single class, one method `ResolveLoss(ESessionLossCause Cause)`.~~ **DONE (DEV-100)** — `Global/SessionLossResolver` (`UWorldSubsystem`). See §1.1. C++ owns the transaction (precedence, money, item loss, autosave); cutscenes / fade / time-skip are delegated to BP via `OnSessionLossResolved`. Implements GDD §4.4:
    - **Police chase precedence**: if a chase is active (between detection and the disengage timer, §10.3), force `Cause = PoliceCapture` regardless of what triggered the loss. Chase always wins.
    - Equipped clothing **stays** equipped (do not strip).
    - Bag placed in world: mark its world record for deletion.
    - Loose clothing on ground: leave as-is at this stage; sleep step finalizes any guaranteed loss.
    - **Energy = 0**: trigger a cutscene → apartment → sleep cycle → guaranteed loss of every world clothing outside the apartment.
    - **Embarrassment = max**: fade to apartment. **No extra cost** (no time skip, no money, no rep).
    - **Police capture (can pay)**: fade to apartment, deduct money penalty, clear `wanted`.
    - **Police capture (can't pay)**: short non-interactive holding-cell cutscene; time fast-forwards to next morning; debt settled; clear `wanted`. Already-accepted commissions still expire at day end with their normal `failurePenalty` — the cutscene does not pause the day clock.
- ~~Wire `StatsManager::IncreaseEmbarrassment` max-hit and energy-zero into~~ the session subsystem — **DONE (DEV-99)**: `USessionManagerSubsystem` subscribes to `EmbarrassmentUpdate` / `EnergyUpdate` and the C++ embarrassment path no longer calls `EndGameEmbarrassed`. DEV-100 routes `OnSessionEnd` into `USessionLossResolver`.
- Add a debug overlay showing the current loss state and what would be lost if a given cause fired.

**Exit criteria:** all four code paths (safe end, embarrassment max, energy zero, police capture) produce the §4.4 outcomes deterministically. Inventory state after each loss matches the §6.6 summary table 1:1.

### Phase 4 — Attributes refactor (1–2 weeks)

- Decision: GAS vs. extended `StatsManager`. Recommend GAS — the embarrassment formula has Pulse, Recognition, Coverage, Day/Night, per-NPC-type weights, and food-buff multipliers (§7.1, §6.7), which is exactly what `UGameplayEffect` is shaped for.
- Add Lust (§7.2), **Pulse (§7.5)**, Recognition (§7.6), Wanted (§7.7), Reputation (§7.8), Followers (§7.9). Money remains in the save schema directly (non-attribute side effects).
- **Hunger / max-energy decay (§7.3):** add a second layer to max energy. `baseMaxEnergy` (gym progression) stays; introduce `effectiveMaxEnergy` (decays at `maxEnergyDecayRate` per in-game hour toward a floor). Eating any food sets `effectiveMaxEnergy` back to `baseMaxEnergy` as a universal hook in the eat-item flow. Sleep does **not** reset hunger. Health Tracker (§9.7) surfaces effective max alongside current energy.
- Implement `GetEffectiveCoverage(EBodyPart)` on `ClothingManager` per §6.3.2 — **`max()` across garments covering the part** (no sum, no underwear halving). Replace the `0.0f` stub in `StatsManager::TickComponent`.
- Lust → masturbate action (Slut-path gated, §7.2). Block the action in BP / quick-action when the player has no Slut investment.
- **Pulse simulation:** rises with running, masturbation, exposure events; decays toward baseline at rest. Modifies embarrassment and lust gain rates (§7.5).
- Recognition rise from Blogger photo events; **face-cover bypass via `Face` + `Eyes` slots** (§7.6); reduction via news-site reporting (§11.1).
- Define the per-rate multiplier interface that food buffs (§6.7) and toy effects (§6.5) will hook into. Don't ship the buffs here; just leave the seams.
- Debug overlay extension: live values + active modifier sources for every attribute.

**Exit criteria:**
1. Observed-while-exposed embarrassment gain reads coverage and modifiers from the attribute system (no more `0.0f` stub).
2. Lust + Pulse simulate correctly and visibly influence embarrassment in a playtest scenario.
3. Recognition increases after a (mocked) photo event and decreases after a news-report action. Face-cover slot occupancy reduces recognition gain.

### Phase 5 — Time + calendar + rent + sleep (3–4 days)

- `UTimeOfDaySubsystem` replacing the BP-implementable time on `NakedDesireGameMode`. 90-day calendar, week boundary, day phase `08:00–20:00` (fix the `09–21` mismatch in `NPCSpawner.cpp:40`).
- Sleep action on apartment bed: triggers the same path as energy-zero (§4.4) for the "items left outside" cleanup, restores energy (clamped to current effective max), autosaves, advances calendar. **Charges the equipped phone to 100%** (§9.8). **Does NOT reset hunger** (§7.3) — only eating clears effective-max decay.
- Weekly rent transaction at week boundary; eviction if money insufficient (game over (run), §3.3).
- **Weekly follower-income auto-deposit** to the bank at week boundary (§7.9, §9.4).
- Endless-mode flag on `UGlobalSaveGameData`; rent-eviction branch checks it.

**Exit criteria:** play through 7 in-game days, get charged rent at the week boundary, eviction triggers on insufficient funds, endless-mode disables eviction, weekly follower income lands in the bank.

### Phase 6 — NPC types + recognition pipeline (1–2 weeks)

- `ENPCType` enum, type-specific BT branches or per-type controller subclasses: Walker / Stalker / Blogger / Snitch / Harasser. **No Helper.**
- Police as a separate AI controller / spawn pipeline. Patrols spawn day **and** night while `wanted` (§7.7 / §10.3). Detection logic (face hidden? + coverage threshold) → chase → break-LOS timer.
- Wanted-poster mechanic: spawn posters in the city; tearing all down clears `wanted` (§10.3).
- Recognition flow: Blogger sight + photo event → article → news-site article state → "report" reduces recognition.
- Wire Snitch's "report to police" → immediate police spawn this session + sets `wanted` (§7.7).

**Exit criteria:** every listed NPC type observably distinct; recognition rises after a Blogger event and can be reduced via news report; Snitch report triggers police spawn and the `wanted` tag that persists across sessions until posters torn down or capture.

### Phase 7 — Commission template system + accept lifecycle (1–2 weeks)

- Replace `MissionsConfig`'s hand-authored daily list with `UCommissionTemplate` + procedural generation per §13.4.
- Add typed objective steps as new `UMissionGoal` subclasses:
    - `BeFullyNaked(duration)`
    - `BeFullyNakedNearNPCs(count, duration)`
    - `WalkNakedDistance(meters)`
    - `MoveDistanceFromClothing(meters)`
    - `BeObservedByNPCType(type, durationOrCount)`
    - `TakePhotoAtLocation(locationTag)` (gated by Phase 8 phone work)
    - `DeliverItemTo(npcOrLocation)` — **player-owned inventory only** (§13.4); the commission does not auto-issue items.
    - `PerformAction(actionId)` — **generator filters path-locked actions** (e.g., `masturbate` is Slut-only).
- **Accept lifecycle (§13.1 / §13.2):**
    - Both daily and weekly require explicit Accept on the forum.
    - Un-accepted commissions carry no penalty; accepted-but-failed apply the template's `failurePenalty`.
    - Weekly rewards include followers; weekly `failurePenalty` is heavier than daily.
- **Instant rewards on completion (§13.1 / §13.2 / §3.1 / §4.3):** money wires to the bank, XP credits to the shared pool, followers update on the profile **at the moment of completion** — not on return home. Replace the current `UMissionsManager::CollectRewards` batched flow with immediate crediting in `OnMissionCompleted`. There is no "collect rewards" step at the apartment.
- **Generator rules:** respect `pathRequirement` (incl. `None`); filter path-locked-action templates by player path investment; substitute a tier-scaled default penalty when `failurePenalty` is empty.

**Exit criteria:** daily commissions regenerate from templates each in-game day; weekly arc is distinct; explicit Accept committed flow works end-to-end; rewards credit instantly on completion (no return-home gate); failed accepts deduct the template penalty; un-accepted commissions never penalize the player.

### Phase 8 — Phone + forum UI + battery + livestream (3–4 weeks)

- Phone as an `AItemActor` (Phase 2 base) with hand / pocket / bag location semantics (§9).
- `PhoneSubsystem` (§17.1): tickable; owns battery %, active app, livestream session lifecycle, charger interaction.
- **Battery (§9.8):**
    - Passive base drain + per-app multiplier (Forum/Bank/Maps/Health Tracker/Gallery ~1×, back-camera ~3×, livestream ~5×). Livestream stacks on top of foreground app.
    - Apartment charger interactable: place phone on it, recharges at a fixed rate.
    - **Portable powerbank**: consumable `UItemInstance` purchasable at Convenience Store (§10.4). Single-use, restores fixed % when consumed. S-size container slot.
    - **Hard shutdown at 0%**: all apps lock; livestream ends and deposits earnings-to-date; future tips forfeit. Phone wakes from a consumed powerbank.
    - **Sleep auto-charges to 100%** (voluntary or energy-zero cutscene).
    - Battery % is part of the phone's `UItemInstance` state; persists across saves.
- Apps: Camera + Gallery, Livestream, Bank, Feetex, Maps, Health Tracker, Forum.
- **Bank app income breakdown (§9.4):** line items by source — commissions, livestream donations, in-stream tip-request completions, underwear sales, weekly follower auto-deposit.
- **Livestream (§9.1.1):**
    - `UStreamSession` tickable UObject — works while phone is held OR placed.
    - Per-tick `streamQualityScore` → `FollowerGainCalculator` for the follower trickle (signed by reputation; shrinks at negative rep).
    - End-of-stream deposits both money and accumulated follower delta.
    - **Tip requests:** phone popup with Accept / Decline + countdown. Accept = spawn live objective tracker (reuse Phase 7 primitives). Complete = tip lands + small follower bonus. Fail = viewer count drops (less passive income for the remainder); no rep hit. Decline / timeout = no effect.
- Photo system: render-to-texture (§17.6 / §21 Q5 — recommended).
- Wire `TakePhotoAtLocation` commission step to actual photo events.
- **Phone models + Electronics Shop (§9.9 / §10.4):**
    - 3 tiers (Starter / Mid / Pro). Each is a `UClothingItem`-style data asset (or dedicated `UPhoneItem` definition) with `CameraQuality`, `LivestreamQuality`, `BatteryCapacity` multipliers.
    - Starter is owned at game start. Mid and Pro are bought in-person at the new **Electronics Shop** location (interactable like Wardrobe / Adult Shop).
    - Player can own multiple phones simultaneously — store them in the wardrobe / inventory as regular `UItemInstance`s. Only the equipped phone is active.
    - Hot-swap from the apartment wardrobe; battery percentage is per-phone-instance and **does not transfer** on swap.
    - Profile state (gallery, follower count, livestream history) lives on the player profile, never on the phone — swapping phones does not move or duplicate this state.
    - `CameraQuality` multiplies `exposureScore` for photo posts (§13.5). `LivestreamQuality` multiplies per-tick `streamQualityScore`. `BatteryCapacity` multiplies the total charge budget (drain rates unchanged).

**Exit criteria:** end-to-end photo loop (capture → gallery → post → follower count updates). Livestream can be started, run while the phone is placed, generate trickle followers + donations, accept and complete a tip request for a bonus, end with payout. Battery drain visibly different per app; charger and powerbank both restore charge; 0% hard-shutdown behaves correctly. Buying a Mid / Pro phone at the Electronics Shop adds it to the wardrobe; equipping it visibly improves photo / stream gain rates per the multipliers.

### Phase 9 — Path progression + content authoring (2 weeks)

- **Single shared XP pool** — not per-path. Add `XP` to the save schema. Player invests XP via the forum profile (§13.3) into any path's attribute pool.
- A path's level is derived from how many upgrades the player has purchased from that path's pool (§5.4 / §7.10) — there is no per-path XP counter.
- Level-gating on clothing (§5.1–5.3) and on path-tagged commission templates (§7).
- Author the vertical-slice content set from GDD §18.1 (15–20 clothing items, 3 bag variants, 8 food items, 20 commission templates, 1 functional district).
- Masturbation gating (§5.1, §7.2) — hide the quick-action entry until the player has at least one Slut-path upgrade.

**Exit criteria:** all three paths have at least 5 unlockable items and 3 path-specific commission templates. Slut-path-locked actions correctly hidden until the player invests. XP spent into one path raises *that* path's level without consuming XP that could go to another path.

### Phase 10 — Remaining systems & polish

- Bag inventory (§6.4) — uses Phase 2's `AItemActor` for world placement.
- **Food (§6.7):**
    - Implement the locked vocabulary: 2 instant effects (energy restore, lust decrease) + 4 timed buffs (stamina regen +, max stamina +, embarrassment-gain resistance, lust-gain resistance).
    - Universal built-in effect: every food restores effective max energy to base max (hunger reset; §7.3 hookpoint from Phase 4).
    - Stacking: different types parallel; same type additive to a per-type cap.
    - Three cooking minigames (slice / stir / cook); scoring modulates buff strength; never poison.
- Gym / beauty salon / adult shop / café / convenience store (§10.4). Convenience Store stocks powerbanks (Phase 8 dep). Adult Shop stocks toy items for the three toy slots (Phase 1 dep).
- Rip & tear (§6.3.5).
- **Theft model (§6.3.4)** — implement `T_grace` / `T_grace_bag` grace timers and per-tick `P_theft` chance roll. No ramp. Hiding-spot mechanic is currently spec-ambiguous (see Working notes) — coordinate before implementing.
- Expose action (§6.3.6) — read `CanExpose` per garment, blocked by overlapping coverage. Also blocked when `BlockExposeAction` is active in the restrictions set.
- **Restrictions enforcement (§6.3.7 / §10.4.1):**
    - Wire each `Block*` flag into the relevant subsystem (`BlockRun` into movement, `BlockPhoneUse` into `PhoneSubsystem`, `BlockMasturbate` into the quick action, `BlockSlotChange(slot)` into `ClothingManager::PutOnClothing` / `RemoveClothing`, etc.).
    - **Restraint removal:** Key + timed-unlock action with a **DBD-style skill-check minigame** (§10.4.1). Rotating pointer + target zone; hits speed up removal; misses do nothing; no fail state. Restraint always comes off when the baseline timer expires.
- **Casino (§10.4 / §10.4.2):** new location, significant scope.
    - Three game UIs: slots (instant single-button), blackjack (vs. dealer NPC, in-game-minute pacing), roulette (multi-bet single spin, in-game-minute pacing). No poker.
    - VIP room interactable: pay per-day entrance fee at reception; access flag clears at next day boundary.
    - Strip-game blackjack and roulette tables in VIP: bet a clothing item from an equipped slot. Lost garments transfer to a **casino lost-and-found** safe inventory keyed to the player; retains `UItemInstance` identity per §6.1. Reclaim by winning back at the same table or paying a flat buy-back fee at reception.
    - Wire casino income/loss into the Bank app income breakdown (§9.4).
- Underwear selling (§15.1) — Feetex drop-box or location drop-off variant. Backed by `DeliverItemTo(npcOrLocation)` from Phase 7.
- Wanted-poster takedown (§10.3) — interaction + spawn placement pass.
- Beach + Train Station locations (§10.4) for full-launch scope.
- Final tuning of all §21 numbers (theft, food caps, battery, tip-request distribution, embarrassment / lust / energy / pulse rates, face-cover magnitudes, casino RTP + VIP fee, phone-tier multipliers, restraint minigame parameters, hunger decay, etc.).

---

## 4. Working notes

Use this section for in-flight decisions, blockers, and open questions that emerge during a phase. Move resolved items into the README's §20 "Resolved Design Decisions" or into git history.

- **Phase 1 critical path:** the save-write-without-state bug is the most damaging current issue — any "save" call destroys progress. Fix the SaveSubsystem before anything else builds on save behaviour.
- **Body-part enum migration:** the existing censorship code in `NakedDesireCharacter::OnClothingEquip` / `OnClothingUnequip` reads `EPrivateBodyPartType`. Migration to `EBodyPart` must update that path or the censorship visibility will silently desync.
- **Slot-vocabulary reshape will break BP references** — coordinate before renaming/adding values in `EClothingSlotType`. The character constructor creates skeletal-mesh components keyed to those names; expect BPs in `Content/Blueprints/Player` to need a touch.
- **Toy items vs. clothing items:** the `UClothingItem` schema (coverage, `CanExpose`, `IsRestrictive`) doesn't fit sex toys cleanly. Strongly recommend a separate `USexToyItem : UItemInstance` (with `LustModifier`, `EmbarrassmentModifier`, `PulseModifier`, `VibrationAudible` fields) rather than overloading `UClothingItem`. Decide before Phase 1 toy work begins.
- **XP is a single shared pool** (GDD §5, §7.10). Do not introduce per-path XP counters in Phase 9 or earlier — a path's level is derived from how much the player has invested into that path's attribute pool.
- **Food buff hookpoints belong in Phase 4** (attribute multiplier interface), even though the food items themselves ship in Phase 10. Leave the seams; don't retrofit later.
- **Hunger hookpoint also belongs in Phase 4.** Add `effectiveMaxEnergy` + decay tick when adding Lust / Pulse / etc., so Phase 10's food items only need to call an existing reset method.
- **README contradiction — follower income cadence.** §7.9 line 433 says "Followers generate money each day"; §9.4 and §13.3 say weekly auto-deposit at week boundary. Don't pick one in code until the GDD is reconciled. Phase 5 implementation depends on resolution.
- **README contradiction — hiding spots vs sleep loss.** §6.3.4's new "Hiding spots" bullet says items have a *chance* of theft after sleep, but §4.4 says sleep = guaranteed loss of anything outside. Phase 10 theft work must wait until the GDD resolves whether hiding spots are an explicit exception to the sleep rule or only affect in-session theft chance.
- **README contradiction — masturbation gating.** §7.2 says non-Slut players "must accept the max-lust handicaps... until they go home and masturbate in home before sleep" — but §5.1 has masturbation as a Slut-path unlock. Phase 4 masturbate-action work needs the spec reconciled: either home masturbation is universally available (with public masturbation gated by path) or non-Slut players cannot masturbate at all.
- **Stale §5.3 Slave path text** in the README still says "(cuffs require NPC help to remove)" — contradicts the Key + minigame removal flow. Phase 6 / Phase 10 work should not implement an NPC removal path; if encountered, treat it as stale documentation.
- _empty beyond this point_
