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`
```python
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.