132 lines
6.0 KiB
Markdown
132 lines
6.0 KiB
Markdown
# 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.
|