Project-M/Docs/Vault/07_Sessions/2026/2026-06-06_Cleanup_Alignment.md

date, type, tags

date	type	tags
2026-06-06	session	session cleanup alignment docs refactor hygiene connectionui uitk

Session 2026-06-06 — Cleanup & alignment (docs, dead code, refactor) before more development

Goal

Operator: "Start a cleanup session — clean up documentation code and align everything in the project so it's ready for more development." Run via /dots-dev (ultracode).

Three large 2026-06-05 sessions (M7 Automation, Game-infrastructure menu/settings/saves, HUD rework to UITK) were done but uncommitted, with session logs + DRs already written. CLAUDE.md had drifted from the code (still described SampleScene as the gameplay scene; nothing on Automation / Saves / UITK / the frontend lifecycle), and the logs had flagged cleanup candidates (legacy IMGUI ConnectionUI, the _Recovery/ artifact).

Intake (AskUserQuestion): deep refactor + docs · delete aggressively · group & commit for me (authorizes git writes; commits land on main, matching the solo history; no push).

Process

• Phase 0–1 (read-only scan): editor-state + git + vault scan; a 3-agent Explore swarm (code/asset audit · doc-delta audit · dead-asset + git-grouping audit). Verified the risky findings myself before acting: ConnectionUI has zero code deps (all hits were <c>ConnectionUI</c> doc-comments); _Recovery = 2 tracked + 1 untracked recovery scenes; no new asmdefs (the new feature folders live inside the existing four — corrected an agent's wrong "add ProjectM.Automation/Persistence rows" suggestion).
• Plan-gate: scoped "deep refactor" to behavior-preserving (DRY / dead-code / readability) — explicitly NOT rewriting working netcode/sim; the determinism-critical paths (ProductionMath.CyclesDue, ConveyorMath.ResolveMoves, BaseRestoreSystem) were left untouched. Approved → executed A→F.

Done

A — Dead-asset deletion (via manage_asset, AssetDatabase-consistent)

• Deleted Assets/_Recovery/ (3 crash-recovery scenes + metas; zero references, not in build settings) and the stray empty Assets/Resources.meta (top-level Assets/Resources/ was empty). Kept Assets/_Project/Resources/ (RuntimePanelSettings + theme) and Assets/UI Toolkit/UnityThemes (UITK default scaffolding).

B — Removed the legacy IMGUI ConnectionUI

• Removed the standalone NetConnectionUI GameObject from Game.unity, DevSandbox.unity, SampleScene.unity (each only held Transform + ConnectionUI); deleted ConnectionUI.cs (+ meta); confirmed zero remaining GUID references in any scene. Repointed the 4 stale doc-comments (GameBootstrap, DebugOverlay, EditorAutoHostSystem, ConnectionConfig) from <c>ConnectionUI</c> to the UITK MainMenuController / WorldLauncher (via script_apply_edits anchor_replace). The UITK frontend menu owns Host/Join+IP everywhere now.

C — Targeted behavior-preserving refactor (all via MCP, verified vs live file)

• DRY'd the duplicated UITK Round/Border helpers: MenuUi is now the canonical home (made public); HudUi's byte-identical copies deleted and its 2 internal call sites + HudSystem's 3 call sites repointed to MenuUi.*. HudUi is now a genuine thin extension.
• HudSystem: cache _huskQuery.CalculateEntityCount() once/frame (was called twice).
• BuildSendSystem: replaced the 6 near-identical hotkey if branches (drifting cell/wcell/… vars) with a static readonly (Key, byte)[] s_BuildHotkeys table + one loop — adding a buildable is now one row.
• Deliberately skipped low-value/higher-risk tidies (SettingsService clamp order, ConveyorTransport struct-array, WorldFeedback lookup, PlayerInput dedup) → logged as a Backlog follow-up.

D — Documentation alignment

• CLAUDE.md (30.7 KB → 36.4 KB, still < the 40 KB limit): rewrote Bootstrap & worlds (AutoConnectPort=0, editor-instant-play vs frontend toggle, MainMenu(0)/Game(1) scene split, on-demand WorldLauncher lifecycle + subscene-streams-into-on-demand-world rule); added an M7 Automation + disk-persistence bullet to Build/structures (replacing the now-false "deferred to post-M7"); replaced the "uGUI HUD" claim with a UITK HUD + build-palette bullet; added build-gotchas (frontend world lifecycle, CreateLocalWorld internal, don't-dispose-worlds-in-a-system, URP m_AssetVersion-from-the-future, raw-Write new-.cs-needs-force-refresh, script_apply_edits anchor/delete_method on ISystems); noted the new feature folders fit the existing four asmdefs (no new assemblies).
• Vault: Milestones (M6 + the 2026-06-04 polish pass → ✅ Done; added rows for the HUD rework + this cleanup), Backlog (ConnectionUI item → done; added a delivered-note + a cleanup-follow-ups section), Home + Systems_Index (date + latest-session pointer). New DR not warranted (hygiene, no new architecture).

Validation

• EditMode 194/194 (ProjectM.Tests.EditMode, 0.29 s) — same count as pre-cleanup → no regressions, no tests lost; proves the whole codebase (refactor + ConnectionUI removal + comment edits) compiles clean.
• Play smoke (focused editor, real netcode): ServerWorld + ClientWorld each conns=1 players=1 (worlds boot → loopback connect → player spawn + replicate → subscene streamed fine after the scene edits); the UITK HUD renders correctly (Cleanup_PlaySmoke.png) — rounded bars (MenuUi.Round), the 6-buildable palette with borders (MenuUi.Border + the hotkey/palette path), "HUSKS 0" (cached count), and no "Net: Connected" IMGUI label (ConnectionUI gone). Console clean of project errors.
• Note: the only console "errors" are engine-internal Asserts — "Access version should be odd when acquiring lock" from Modules/Audio/Public/DualThreadManager.h:197 — that fire on domain reload / in Play. They are NOT from project code (audio-thread engine noise), are Assert-level, and don't affect tests/runtime. Left as-is (not a cleanup-pass concern).

Decisions

No DR (hygiene pass). Reaffirmed conventions: edit Assets/*.cs only via MCP; script_apply_edits anchor_replace/delete_method are safe for comment/method edits even on a struct : ISystem; manage_asset delete keeps the AssetDatabase consistent for asset removals.

Next-session intent

• Resume feature work on the now-aligned, committed base. Candidate threads from the M7 follow-ups: throughput/belt visuals (one replicated byte), recipe depth (multi-input fabricator, fabricator→conveyor chaining), per-machine meshes; operator live play-through + a real 2-build LAN run.
• Optional code-tidy follow-ups (logged in Backlog) if churn budget allows.