diff --git a/war-room-migration-plan-v2.md b/war-room-migration-plan-v2.md new file mode 100644 index 00000000..607723fc --- /dev/null +++ b/war-room-migration-plan-v2.md @@ -0,0 +1,131 @@ +# 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 +│ └── / # 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.