manual_slop/conductor/tracks/codebase_migration_20260302/plan.md

Implementation Plan: Codebase Migration to src & Cleanup (codebase_migration_20260302)

Phase 1: Unused File Identification & Removal

• Task: Initialize MMA Environment activate_skill mma-orchestrator
• Task: Audit Codebase for Dead Files
  • WHERE: Project root
  • WHAT: Run py_find_usages or grep on suspected unused files to verify they are not referenced by gui_2.py, tests/, simulation/, or core config files.
  • HOW: Gather a list of unused files.
  • SAFETY: Do not delete files referenced in .toml files or Github action workflows.
• Task: Delete Unused Files
  • WHERE: Project root
  • WHAT: Use run_powershell with Remove-Item to delete the identified unused files.
  • HOW: Explicitly list and delete them.
  • SAFETY: Stage deletions to Git carefully.
• Task: Conductor - User Manual Verification 'Phase 1: Unused File Identification & Removal' (Protocol in workflow.md)

Phase 2: Directory Restructuring & Migration

• Task: Create src/ Directory
  • WHERE: Project root
  • WHAT: Create the src/ directory. Add an empty __init__.py to make it a package.
  • HOW: New-Item -ItemType Directory src; New-Item src/__init__.py.
  • SAFETY: None.
• Task: Move Application Files to src/
  • WHERE: Project root
  • WHAT: Move core .py files (gui_2.py, ai_client.py, mcp_client.py, shell_runner.py, project_manager.py, events.py, etc.) into src/.
  • HOW: Use git mv via run_powershell or standard Move-Item.
  • SAFETY: Preserve git history of these files.
• Task: Conductor - User Manual Verification 'Phase 2: Directory Restructuring & Migration' (Protocol in workflow.md)

Phase 3: Entry Point & Import Resolution

• Task: Create sloppy.py Entry Point
  • WHERE: Project root (sloppy.py)
  • WHAT: Create the script to act as the primary launch point. It should import App from src.gui_2 and pass CLI args.
  • HOW: Write a standard Python script wrapper.
  • SAFETY: Ensure it correctly propagates sys.argv.
• Task: Resolve Absolute and Relative Imports
  • WHERE: src/*.py, tests/*.py, simulation/*.py
  • WHAT: Update import statements. E.g., import gui_2 becomes from src import gui_2 or adjust sys.path.append in tests.
  • HOW: Surgical string replacements. Ensure pytest can still find fixtures and test modules.
  • SAFETY: Run uv run pytest to aggressively check for ModuleNotFoundErrors.
• Task: Conductor - User Manual Verification 'Phase 3: Entry Point & Import Resolution' (Protocol in workflow.md)

Phase 4: Final Validation & Documentation

• Task: Full Test Suite Validation
  • WHERE: Project root
  • WHAT: Run uv run pytest. Fix any remaining path resolution issues for logs, artifacts, and configs.
  • HOW: Verify 100% pass rate.
  • SAFETY: Artifacts must still be written to tests/artifacts/.
• Task: Update Core Documentation
  • WHERE: Readme.md, docs/, conductor/tech-stack.md
  • WHAT: Document sloppy.py as the new entry point. Document the src/ directory layout.
  • HOW: Surgical text replacement.
  • SAFETY: Accurate representation of new structure.
• Task: Conductor - User Manual Verification 'Phase 4: Final Validation & Documentation' (Protocol in workflow.md)