add checklists

2026-05-19 10:18:28 +00:00
parent 414a16c718
commit 08fe41d296
3 changed files with 788 additions and 0 deletions
--- a/docs/checklists/clean-slate-refactor.md
+++ b/docs/checklists/clean-slate-refactor.md
@@ -0,0 +1,346 @@
+# Clean Slate Refactoring — Implementation Checklist
+
+**Source Plan:** [`docs/architecture/CLEAN_SLATE_PLAN.md`](../architecture/CLEAN_SLATE_PLAN.md)
+**Master Document:** [`UE5_Modular_Game_Framework.md`](../../UE5_Modular_Game_Framework.md)
+**Audit:** [`docs/blueprints/AUDIT_REPORT.md`](../../docs/blueprints/AUDIT_REPORT.md)
+**Template:** [`docs/blueprints/TEMPLATE.md`](../../docs/blueprints/TEMPLATE.md)
+
+---
+
+## Phase 0 — Setup
+
+- [ ] 0.1 Verify current `git status` is clean (commit any pending changes first)
+- [ ] 0.2 Create branch `refactor/clean-slate` from `main`
+- [ ] 0.3 Confirm all 83 blueprint files are readable and not corrupted
+
+---
+
+## Phase 1 — Rename 18 Files to Match Master Naming
+
+Each task: delete old file, create new file at same location with corrected name, update internal header line.
+
+### 03-interaction/
+- [ ] 1.1 Rename `20_BPC_InteractableDoorComponent.md` → `BP_DoorActor.md`
+
+### 04-inventory/
+- [ ] 1.2 Rename `22_BPC_InventoryComponent.md` → `BPC_InventorySystem.md`
+- [ ] 1.3 Rename `25_BPC_EquipmentSystem.md` → `BPC_EquipmentSlotSystem.md`
+
+### 05-saveload/
+- [ ] 1.4 Rename `30_BPC_CheckpointSystem.md` → `BP_Checkpoint.md` (if Master uses BP_ prefix; verify against Master line)
+
+### 06-ui/
+- [ ] 1.5 Rename `33_WBP_HUD.md` → `WBP_HUDController.md`
+- [ ] 1.6 Rename `34_WBP_InventoryUI.md` → `WBP_InventoryMenu.md`
+- [ ] 1.7 Rename `35_WBP_InteractionUI.md` → `WBP_InteractionPromptDisplay.md`
+
+### 07-narrative/
+- [ ] 1.8 Rename `45_BPC_EndingAccumulatorSystem.md` → `BPC_EndingAccumulator.md`
+- [ ] 1.9 Rename `47_BPC_NarrativeTriggerVolume.md` → `BP_NarrativeTriggerVolume.md`
+
+### 08-weapons/
+- [ ] 1.10 Rename `50_BP_RangedWeapon.md` → `BPC_FirearmSystem.md`
+- [ ] 1.11 Rename `51_BP_MeleeWeapon.md` → `BPC_MeleeSystem.md`
+- [ ] 1.12 Rename `53_BPC_DamageHandlerComponent.md` → `BPC_DamageReceptionSystem.md`
+
+### 09-ai/
+- [ ] 1.13 Rename `55_BPC_AIControllerBase.md` → `AI_BaseAgentController.md`
+- [ ] 1.14 Rename `56_BPC_PerceptionComponent.md` → `BPC_AIPerceptionSystem.md`
+
+### 10-adaptive/
+- [ ] 1.15 Rename `64_BPC_AtmosphereController.md` → `BPC_AtmosphereStateController.md`
+- [ ] 1.16 Rename `65_BPC_LightingManager.md` → `BPC_LightEventController.md`
+- [ ] 1.17 Rename `66_BPC_AudioManager.md` → `BPC_AudioAtmosphereController.md`
+
+### Verify
+- [ ] 1.18 Verify all 18 renamed files exist and old files are deleted
+
+---
+
+## Phase 2 — Split Two Bundled Files
+
+### 2.1 Split DeathHandlingSystem (1 file → 5 files)
+
+**Read source:** `05-saveload/31_BPC_DeathHandlingSystem.md` (311 lines)
+
+- [ ] 2.1.1 Create `05-saveload/BPC_DeathHandlingSystem.md` — Core orchestrator content (lines 1-64 enums/structs + 206-311 core vars/fns/flow/matrix + header section)
+- [ ] 2.1.2 Create `05-saveload/BPC_AltDeathSpaceSystem.md` — Alt death space sub-system (lines 65-99)
+- [ ] 2.1.3 Create `05-saveload/BPC_PersistentCorpseSystem.md` — Corpse sub-system (lines 102-132)
+- [ ] 2.1.4 Create `05-saveload/BPC_PlayerRespawnSystem.md` — Respawn sub-system (lines 136-167)
+- [ ] 2.1.5 Create `05-saveload/BPC_RunHistoryTracker.md` — Run history sub-system (lines 171-203)
+
+**Each split file must:**
+- Include a `Depends On:` section referencing the orchestrator and relevant systems
+- Include a `Purpose:` header describing its standalone role
+- Follow TEMPLATE.md format with complete sections
+
+- [ ] 2.1.6 Delete original `05-saveload/31_BPC_DeathHandlingSystem.md`
+- [ ] 2.1.7 Verify all 5 new files are self-contained and valid
+
+### 2.2 Split MenuWidgets (1 file → 7 files)
+
+**Read source:** `06-ui/36_WBP_MenuWidgets.md` (353 lines)
+
+- [ ] 2.2.1 Create `06-ui/WBP_MainMenu.md` — Main menu widget (lines 15-48)
+- [ ] 2.2.2 Create `06-ui/WBP_PauseMenu.md` — Pause menu widget (lines 51-94)
+- [ ] 2.2.3 Create `06-ui/WBP_SettingsMenu.md` — Settings menu widget (lines 99-188)
+- [ ] 2.2.4 Create `06-ui/WBP_NotificationToast.md` — Toast notification widget (lines 191-230)
+- [ ] 2.2.5 Create `06-ui/WBP_ScreenEffectController.md` — Screen effects widget (lines 233-261)
+- [ ] 2.2.6 Create `06-ui/WBP_MenuFlowController.md` — Menu flow widget (lines 264-353)
+- [ ] 2.2.7 Create `06-ui/WBP_ObjectiveDisplay.md` — New file (not in bundled source; Master Sec 6.6)
+
+**Note for 2.2.7:** `WBP_ObjectiveDisplay` is listed in Master Section 6.6 but was NOT in the bundled `WBP_MenuWidgets.md`. Create from scratch using TEMPLATE.md. It displays current objectives as an overlay.
+
+- [ ] 2.2.8 Delete original `06-ui/36_WBP_MenuWidgets.md`
+- [ ] 2.2.9 Verify all 7 new files are self-contained and valid
+
+---
+
+## Phase 3 — Create 12 Data Asset Spec Files (new `14-data-assets/` directory)
+
+All DA files should follow this structure:
+```
+# DA_<Name> — Data Asset
+**Parent Class:** `UDataAsset`
+**Dependencies:** (systems that consume this data)
+**Purpose:** (what content this data asset defines)
+
+## Variables / Structure
+(complete row structure definition)
+
+## Gameplay Tags
+(tag namespace this DA operates in)
+
+## Validation Rules
+(editor-time validation logic)
+
+## Example Data
+(1-2 example rows)
+
+## Consumed By
+(systems that read this DA)
+
+## Reuse Notes
+```
+
+- [ ] 3.0 Create directory `docs/blueprints/14-data-assets/`
+- [ ] 3.1 Create `14-data-assets/DA_DataAssetArchitecture.md` — overview of all 20 DA types, naming conventions, dependency rules
+- [ ] 3.2 Create `14-data-assets/DA_InteractionData.md`
+- [ ] 3.3 Create `14-data-assets/DA_ObjectiveData.md`
+- [ ] 3.4 Create `14-data-assets/DA_EncounterData.md`
+- [ ] 3.5 Create `14-data-assets/DA_AtmosphereProfile.md`
+- [ ] 3.6 Create `14-data-assets/DA_ScareEvent.md`
+- [ ] 3.7 Create `14-data-assets/DA_RoomMutation.md`
+- [ ] 3.8 Create `14-data-assets/DA_BehaviourVariant.md`
+- [ ] 3.9 Create `14-data-assets/DA_HapticProfile.md`
+- [ ] 3.10 Create `14-data-assets/DA_AdaptationRule.md`
+- [ ] 3.11 Create `14-data-assets/DA_EquipmentConfig.md`
+- [ ] 3.12 Create `14-data-assets/DA_PuzzleData.md`
+- [ ] 3.13 Create `14-data-assets/DA_RareEvent.md`
+
+---
+
+## Phase 4 — Create 30 Runtime System Spec Files
+
+### 03-interaction/ (4 files)
+- [ ] 4.1 Create `03-interaction/BPC_PhysicsDragSystem.md`
+- [ ] 4.2 Create `03-interaction/BPC_ContextualTraversalSystem.md`
+- [ ] 4.3 Create `03-interaction/BP_PuzzleDeviceActor.md`
+- [ ] 4.4 Create `03-interaction/BPC_UsableWorldObjectSystem.md`
+
+### 04-inventory/ (7 files)
+- [ ] 4.5 Create `04-inventory/BPC_ActiveItemSystem.md`
+- [ ] 4.6 Create `04-inventory/BPC_ItemCombineSystem.md`
+- [ ] 4.7 Create `04-inventory/BPC_DocumentArchiveSystem.md`
+- [ ] 4.8 Create `04-inventory/BPC_JournalSystem.md`
+- [ ] 4.9 Create `04-inventory/BPC_CollectibleTracker.md`
+- [ ] 4.10 Create `04-inventory/BPC_ConsumableSystem.md`
+- [ ] 4.11 Create `04-inventory/BPC_KeyItemSystem.md`
+
+### 05-saveload/ (1 file)
+- [ ] 4.12 Create `05-saveload/BPC_PersistentWorldStateRecorder.md`
+
+### 06-ui/ (3 files)
+- [ ] 4.13 Create `06-ui/WBP_DiegeticHUDFrame.md`
+- [ ] 4.14 Create `06-ui/WBP_JournalDocumentViewer.md`
+- [ ] 4.15 Create `06-ui/WBP_ObjectiveDisplay.md` (already created in Phase 2.2.7)
+
+### 08-weapons/ (5 files)
+- [ ] 4.16 Create `08-weapons/BPC_RecoilSystem.md`
+- [ ] 4.17 Create `08-weapons/BPC_ReloadSystem.md`
+- [ ] 4.18 Create `08-weapons/BPC_ShieldDefenseSystem.md`
+- [ ] 4.19 Create `08-weapons/BPC_HitReactionSystem.md`
+- [ ] 4.20 Create `08-weapons/BPC_DeathCauseTracker.md`
+
+### 09-ai/ (3 files)
+- [ ] 4.21 Create `09-ai/BB_AgentBoard.md`
+- [ ] 4.22 Create `09-ai/BPC_AIMemorySystem.md`
+- [ ] 4.23 Create `09-ai/BPC_BehaviourVariantSelector.md`
+
+### 10-adaptive/ (6 files)
+- [ ] 4.24 Create `10-adaptive/BPC_PlaystyleClassifier.md`
+- [ ] 4.25 Create `10-adaptive/BPC_AdaptiveEnvironmentDirector.md`
+- [ ] 4.26 Create `10-adaptive/BPC_MemoryDriftSystem.md`
+- [ ] 4.27 Create `10-adaptive/BPC_ScareEventSystem.md`
+- [ ] 4.28 Create `10-adaptive/BPC_PacingDirector.md`
+- [ ] 4.29 Create `10-adaptive/BPC_RareEventSystem.md`
+
+---
+
+## Phase 5 — Reorganize 11-polish/ into 3 New Directories
+
+### 5.1 Create new directories
+- [ ] 5.1.1 Create `docs/blueprints/11-meta/`
+- [ ] 5.1.2 Create `docs/blueprints/12-settings/`
+- [ ] 5.1.3 Create `docs/blueprints/13-polish/`
+
+### 5.2 Move files to 11-meta/ (3 files)
+- [ ] 5.2.1 Move `11-polish/74_BPC_AchievementManager.md` → `11-meta/SS_AchievementSystem.md`
+- [ ] 5.2.2 Move `11-polish/75_BPC_StatsTracker.md` → `11-meta/BPC_ProgressStatTracker.md`
+- [ ] 5.2.3 Create `11-meta/BPC_EndingCompletionTracker.md` (new)
+- [ ] 5.2.4 Create `11-meta/BPC_MetaProgressionSystem.md` (new)
+- [ ] 5.2.5 Create `11-meta/BPC_RunSummarySystem.md` (new)
+
+### 5.3 Move files to 12-settings/ (4 files)
+- [ ] 5.3.1 Move `11-polish/71_SS_SettingsManager.md` → `12-settings/SS_SettingsSystem.md`
+- [ ] 5.3.2 Move `11-polish/72_BPC_AccessibilitySettings.md` → `12-settings/BPC_AccessibilitySettings.md`
+- [ ] 5.3.3 Create `12-settings/BPC_HapticsController.md` (new)
+- [ ] 5.3.4 Create `12-settings/BPC_PlatformServiceAbstraction.md` (new)
+
+### 5.4 Move remaining files to 13-polish/ (9 files)
+- [ ] 5.4.1 Move `11-polish/73_BPC_TutorialSystem.md` → `13-polish/BPC_TutorialSystem.md`
+- [ ] 5.4.2 Move `11-polish/76_BPC_LoadingScreen.md` → `13-polish/BPC_LoadingScreen.md`
+- [ ] 5.4.3 Move `11-polish/77_WBP_CreditsScreen.md` → `13-polish/WBP_CreditsScreen.md`
+- [ ] 5.4.4 Move `11-polish/78_WBP_SplashScreen.md` → `13-polish/WBP_SplashScreen.md`
+- [ ] 5.4.5 Move `11-polish/79_BPC_FPSCounter.md` → `13-polish/BPC_FPSCounter.md`
+- [ ] 5.4.6 Move `11-polish/80_BPC_DevCheatManager.md` → `13-polish/BPC_DevCheatManager.md`
+- [ ] 5.4.7 Move `11-polish/81_WBP_DebugMenu.md` → `13-polish/WBP_DebugMenu.md`
+- [ ] 5.4.8 Move `11-polish/82_BPC_AnalyticsTracker.md` → `13-polish/BPC_AnalyticsTracker.md`
+- [ ] 5.4.9 Move `11-polish/83_BPC_ErrorHandler.md` → `13-polish/BPC_ErrorHandler.md`
+
+### 5.5 Clean up
+- [ ] 5.5.1 Delete empty `11-polish/` directory
+
+---
+
+## Phase 6 — Delete Extra/Unmatched Files (7 files)
+
+These files define systems not present in the Master document or are replaced by split/new files:
+
+- [ ] 6.1 Delete `03-interaction/17_BPC_PickupComponent.md` (covered by ItemPickup + InteractionExecutor)
+- [ ] 6.2 Delete `03-interaction/19_BPC_LeverPuzzleComponent.md` (covered by BP_PuzzleDeviceActor)
+- [ ] 6.3 Delete `04-inventory/23_BPC_InventoryWeightSystem.md` (sub-feature of InventorySystem)
+- [ ] 6.4 Delete `04-inventory/24_BPC_InventoryQuickSlot.md` (sub-feature of ActiveItemSystem)
+- [ ] 6.5 Delete `09-ai/57_BPC_BehaviorTreeManager.md` (covered by BB_AgentBoard + BehaviourVariantSelector)
+- [ ] 6.6 Delete `10-adaptive/68_BP_DynamicEvent.md` (covered by BPC_RareEventSystem)
+- [ ] 6.7 Delete `10-adaptive/67_BPC_VFXManager.md` (not in Master; VFX controlled by AtmosphereController)
+
+---
+
+## Phase 7 — Renumber All Files Sequentially
+
+After all renames/splits/creates/moves/deletes, renumber every file prefixed with `XX_` (where XX is the existing number).
+
+**New numbering order:**
+1. 01-core/ → 01–12
+2. 02-player/ → 13–21
+3. 03-interaction/ → 22–32
+4. 04-inventory/ → 33–44
+5. 05-saveload/ → 45–53
+6. 06-ui/ → 54–66
+7. 07-narrative/ → 67–77
+8. 08-weapons/ → 78–89
+9. 09-ai/ → 90–98
+10. 10-adaptive/ → 99–107
+11. 11-meta/ → 108–113
+12. 12-settings/ → 114–118
+13. 13-polish/ → 119–128
+14. 14-data-assets/ → 129–141
+
+**Renumbering rules:**
+- Each file gets prefix `XX_` where XX is zero-padded to 2 digits
+- The prefix matches the directory's slot in the numbering order
+- Example: `01-core/01_GI_GameFramework.md` stays `01_`. `06-ui/` files get `54_` through `66_`.
+- Internal cross-references in each file must be updated to new filenames
+
+- [ ] 7.1 Renumber 01-core/ files (7 files → verify, may need expansion to 12)
+- [ ] 7.2 Renumber 02-player/ files (9 files → 13–21)
+- [ ] 7.3 Renumber 03-interaction/ files (11 files → 22–32)
+- [ ] 7.4 Renumber 04-inventory/ files (12 files → 33–44)
+- [ ] 7.5 Renumber 05-saveload/ files (9 files → 45–53)
+- [ ] 7.6 Renumber 06-ui/ files (13 files → 54–66)
+- [ ] 7.7 Renumber 07-narrative/ files (11 files → 67–77)
+- [ ] 7.8 Renumber 08-weapons/ files (12 files → 78–89)
+- [ ] 7.9 Renumber 09-ai/ files (9 files → 90–98)
+- [ ] 7.10 Renumber 10-adaptive/ files (9 files → 99–107)
+- [ ] 7.11 Renumber 11-meta/ files (6 files → 108–113)
+- [ ] 7.12 Renumber 12-settings/ files (5 files → 114–118)
+- [ ] 7.13 Renumber 13-polish/ files (10 files → 119–128)
+- [ ] 7.14 Renumber 14-data-assets/ files (13 files → 129–141)
+
+---
+
+## Phase 8 — Update Cross-References
+
+After renumbering, every internal cross-reference in every file must point to the correct filename.
+
+- [ ] 8.1 Search all `.md` files for `](XX_` patterns
+- [ ] 8.2 Verify each link target exists at the referenced path
+- [ ] 8.3 Fix any broken or stale links
+
+---
+
+## Phase 9 — Update AUDIT_REPORT.md
+
+- [ ] 9.1 Update all status columns to ✅ for previously missing/bundled systems
+- [ ] 9.2 Update file counts (final: ~141 files, 0 missing)
+- [ ] 9.3 Remove "Recommendations" section (all completed)
+- [ ] 9.4 Add "Resolved" section documenting what was done
+
+---
+
+## Phase 10 — Update CONTEXT.md
+
+- [ ] 10.1 Update directory structure to reflect all 14 directories
+- [ ] 10.2 Update file count to ~141
+- [ ] 10.3 Update build order to 14 phases
+- [ ] 10.4 Update naming conventions reference
+- [ ] 10.5 Mark Clean Slate refactoring as complete
+
+---
+
+## Phase 11 — Final Verification
+
+- [ ] 11.1 Run `list_files` recursively on `docs/blueprints/` — verify 14 directories, ~141 files
+- [ ] 11.2 Cross-reference: every Master system (Section 1–12) should have exactly 1 file
+- [ ] 11.3 Cross-reference: all 20 Data Asset types from Section 13 have a spec
+- [ ] 11.4 Verify no duplicate system names across directories
+- [ ] 11.5 Verify all files follow TEMPLATE.md format (header, enums, structs, variables, functions, dispatchers, flow, communications, reuse)
+- [ ] 11.6 Verify sequential numbering from 01 to 141
+- [ ] 11.7 Run `git status` — should show renames, new files, deleted files, no orphaned files
+
+---
+
+## Phase 12 — Git Commit
+
+- [ ] 12.1 Stage all changes
+- [ ] 12.2 Commit with message: `refactor: clean slate — 1:1 master-to-file mapping for all 141 systems`
+- [ ] 12.3 Verify commit is clean
+- [ ] 12.4 (Optional) Create PR to main
+
+---
+
+## Notes for Execution Agent
+
+1. **Use `apply_diff` for renaming file header lines** — change the `# XX_SystemName` line only
+2. **Use `write_to_file` for creating new files** (always with complete content)
+3. **Use `delete_file` for removing obsolete files**
+4. **NEVER use `sed`, `awk`, or `cat >`** for file operations
+5. **Read the Master document section** for each new file before writing it to get accurate variable/function definitions
+6. **Follow TEMPLATE.md religiously** — every new file must have all required sections
+7. **Commit after each Phase** (not after every file) to keep git history reasonable
+8. **If a Master section is unclear on a detail**, use the conventions from nearby systems and document the assumption in Reuse Notes
+
+---
+
+*Checklist created 2026-05-18*