Atomizer/war-room-migration-plan-v2.md

War-Room Migration Plan v2 — Projects-First Architecture

Date: 2026-02-23 Adapted by: Manager Reviewer: Auditor (Codex 5.3) Original: war-room-migration-plan.md (2026-02-20)

Key Change from v1

Top-level studies/ folder is eliminated. All work lives under projects/, where each project is self-contained per the Atomizer Project Standard. Studies are nested inside their parent project.

New repo structure

Atomizer/
├── projects/                        # Canonical project home (Project Standard)
│   ├── hydrotech-beam/              # ✅ already exists
│   ├── isogrid-dev-plate/           # ✅ already exists
│   └── <future projects>/           # Created per Project Standard when needed
├── studies/                         # ⚠️ LEGACY — kept as-is, not actively used
│   ├── M1_Mirror/                   #   Migrated into projects/ one-at-a-time
│   ├── UAV_Arm/                     #   when the project becomes active
│   ├── ...                          #   (restructured to new standard at that time)
├── optimization_engine/
├── templates/
├── ...

Migration strategy: INCREMENTAL

• No bulk migration. Legacy studies/ stays untouched.
• projects/ is the new canonical root for all code paths.
• When a legacy study becomes active, it gets migrated into a proper project under projects/ and restructured to the Project Standard at that time.
• New projects are always created under projects/.

---

Phase 0 — Stop The Bleeding (P0, 1-2 days)

Unchanged from v1. Fix broken imports, plugin paths, smoke tests. No folder moves yet.

Phase 1 — Entrypoint Contract Unification (P0, 2-4 days)

Unchanged from v1. Canonical runner API (optimization_engine/app/runner_service.py).

Addition: The canonical runner must resolve study paths via a project-aware resolver (see Phase 2).

Phase 2 — Projects-First Code Migration (P0, 2-3 days) ⬅️ NEW

Replaces v1 "Study Script Decoupling"

2A — No folder moves

Legacy studies/ stays as-is. No bulk migration. Projects get migrated individually when they become active.

2B — Update code paths to use projects/ as primary

Files referencing studies/ that need updating:

File	Reference type	Action
atomizer.py (lines 135, 193, 301-310, 373-377, 443, 538, 573-598)	PROJECT_ROOT / "studies"	Change to PROJECT_ROOT / "projects" with project-aware resolver
optimization_engine/validators/results_validator.py (line 468)	Path(f"studies/{study_name}")	Update to project-relative path
optimization_engine/validators/config_validator.py (line 12)	Docstring example	Update path
optimization_engine/insights/__init__.py (lines 51-77)	Docstring examples	Update paths
optimization_engine/templates/__init__.py (line 155)	Example display	Update path
optimization_engine/devloop/planning.py (lines 298-345)	studies/_Other/ hardcoded	Update to use projects/ with legacy fallback
optimization_engine/processors/surrogates/*.py	Hardcoded Windows paths	Update to project-relative
optimization_engine/gnn/*.py	Hardcoded Windows paths	Update to project-relative

2C — Project-aware study resolver (with legacy fallback)

New module: optimization_engine/app/study_resolver.py

def resolve_study(study_name: str, project: str = None) -> Path:
    """
    Resolve study path. Search order:
    1. projects/{project}/studies/{study_name} (if project specified)
    2. projects/*/studies/{study_name} (search all projects)
    3. studies/{study_name} (legacy fallback)
    """

CLI changes:

• atomizer list-studies → atomizer list-studies [--project X] (lists from projects/ + legacy studies/)
• atomizer neural-optimize --study X → add optional --project P flag, auto-resolve with fallback
• atomizer create-study → requires --project (new studies always go in projects/)

2D — Legacy studies/ gets a README

studies/README.md:
"Legacy study folder. New work goes in projects/. 
These studies will be migrated into projects/ individually when needed."

---

Phase 3 — Hooks/Plugins Hardening (P1, 3-5 days)

Unchanged from v1.

Phase 4 — Extractor Surface Rationalization (P1, 1 week)

Unchanged from v1.

Phase 5 — Template/Study Generation Repair (P1, 2-4 days)

Updated: atomizer create-study must now:

1. Accept --project flag (required)
2. Generate study inside projects/{project}/studies/{study_name}/
3. Create project scaffold if project doesn't exist yet (with confirmation)

Phase 6 — Future Folder Re-homing (P2, 1 week)

Unchanged from v1.

Phase 7 — Verification and Guardrails (P0 ongoing)

Updated tests:

• test_project_structure.py — validate all projects have required subdirs
• test_study_resolver.py — study lookup works across projects
• test_no_toplevel_studies.py — fail if studies/ dir exists at repo root
• Original tests from v1 still apply

---

Dependency-Critical Ordering Summary

1. Phase 0 — import/plugin path fixes (no folder moves)
2. Phase 1 — canonical runner contract
3. Phase 2 — projects-first migration (folder moves + path updates + resolver)
4. Phase 5 — template generation updated for projects
5. Phase 3 — hooks hardening
6. Phase 4 + 6 — extractor/future rationalization
7. Phase 7 — continuously

Quick Wins (do first in Phase 2)

1. Add --project flag to CLI + study resolver with legacy fallback
2. Update atomizer.py to search projects/ first, studies/ second
3. Add README to studies/ marking it legacy
4. Update docstring examples

Risk Notes

• Zero breaking changes: legacy studies/ untouched, resolver falls back to it
• Windows hardcoded paths: GNN test files reference C:/Users/Antoine/Atomizer/studies/... — low priority, update when those projects get migrated
• Syncthing: no changes needed now since studies/ stays. Update sync config only when individual projects migrate.