auto: daily sync

war-room-codex-analysis.md

@@ -0,0 +1,194 @@
+# War-Room Codex Analysis (Code-Level Reality)
+
+Date: 2026-02-20
+Scope: Static + runtime checks starting from `atomizer.py` and `optimization_engine/run_optimization.py`.
+
+## 1) Entry Point Reality
+
+### A. `atomizer.py` is runnable
+- Verified: `python3 atomizer.py --help` exits `0`.
+- Top-level imports are valid.
+- Command handlers branch into two very different worlds:
+  - **Atomizer UX path**: `intake`, `gate`, `finalize`.
+  - **Legacy study-script launcher**: `neural-optimize` shells into per-study `studies/<name>/run_optimization.py`.
+
+### B. `optimization_engine/run_optimization.py` is currently broken at import time
+- Verified: `python3 optimization_engine/run_optimization.py --help` exits `1`.
+- Failure:
+  - `optimization_engine/run_optimization.py:39`
+  - imports `optimization_engine.future.llm_optimization_runner`
+  - which imports `optimization_engine.extractor_orchestrator` at `optimization_engine/future/llm_optimization_runner.py:26`
+  - but only `optimization_engine/future/extractor_orchestrator.py` exists.
+- Result: this entrypoint never reaches argument parsing.
+
+## 2) Import Chains and Dependency Graph
+
+## 2.1 Atomizer chain (actual reachable modules)
+
+```mermaid
+graph TD
+  A[atomizer.py]
+  A --> TL[optimization_engine.config.template_loader]
+  A --> AT[optimization_engine.processors.surrogates.auto_trainer]
+  A --> SV[optimization_engine.validators.study_validator]
+  A --> IN[optimization_engine.intake]
+  A --> VG[optimization_engine.validation]
+  A --> HR[optimization_engine.reporting.html_report]
+
+  SV --> CV[validators.config_validator]
+  SV --> MV[validators.model_validator]
+  SV --> RV[validators.results_validator]
+```
+
+Key behavior:
+- `neural-optimize` does **not** call a central engine runner; it executes `studies/<study>/run_optimization.py` via subprocess.
+- This makes runtime behavior depend on many heterogeneous study scripts.
+
+## 2.2 Unified runner chain (intended, but broken)
+
+```mermaid
+graph TD
+  R[optimization_engine/run_optimization.py]
+  R --> WA[future.llm_workflow_analyzer]
+  R --> LR[future.llm_optimization_runner]
+  R --> NXU[nx.updater]
+  R --> NXS[nx.solver]
+  R --> CR[core.runner]
+
+  LR --> HM[plugins.hook_manager]
+  LR -.broken import.-> EO[optimization_engine.extractor_orchestrator (missing)]
+  LR -.broken import.-> IC[optimization_engine.inline_code_generator (missing)]
+  LR -.broken import.-> HG[optimization_engine.hook_generator (missing)]
+```
+
+Observations:
+- `OptimizationRunner` is imported in `optimization_engine/run_optimization.py:40` but not used.
+- Manual mode is scaffolding and exits (`optimization_engine/run_optimization.py:286-320`).
+
+## 3) Tight vs Loose Coupling
+
+### Tight coupling (high-risk refactor areas)
+- `atomizer.py` to repository layout (`studies/<study>/run_optimization.py`) and command shelling.
+- `core/runner.py` to config schema and exact extractor return shape (`result[metric_name]`).
+- Validation gate and intake to specific extractor functions and NX solver assumptions.
+- Template loader to incorrect engine-relative paths and missing module names.
+
+### Loose coupling (good seams)
+- Hook function interface (`dict -> optional dict`) is flexible.
+- Extractor call abstraction (`name -> callable`) in runners can be standardized.
+- Lazy imports in `atomizer.py` for intake/gate/finalize reduce startup coupling.
+
+## 4) Circular Dependencies
+
+Detected import cycles are limited and not the main blocker:
+- `optimization_engine.extractors -> optimization_engine.extractors.extract_zernike_figure -> optimization_engine.extractors`
+- `optimization_engine.model_discovery -> optimization_engine.model_discovery` (package self-cycle artifact)
+
+Main instability is from **missing/incorrect module paths**, not classic circular imports.
+
+## 5) Dead Code / Orphan Findings
+
+## 5.1 `optimization_engine/future/` (what is actually wired)
+
+Direct non-test references:
+- `llm_workflow_analyzer.py`: referenced by `optimization_engine/run_optimization.py`.
+- `llm_optimization_runner.py`: referenced by `optimization_engine/run_optimization.py` and some study scripts.
+- `report_generator.py`: referenced by dashboard backend route.
+
+Mostly test/deprecation only:
+- `research_agent.py`, `step_classifier.py`, `targeted_research_planner.py`, `workflow_decomposer.py`, `pynastran_research_agent.py`.
+
+Practically dead due broken imports:
+- `future/extractor_orchestrator.py`, `future/inline_code_generator.py`, `future/hook_generator.py` are intended runtime pieces, but callers import them using missing top-level paths.
+
+## 5.2 Extractors (used vs orphaned)
+
+Clearly used in runtime paths:
+- `extract_displacement.py`, `extract_von_mises_stress.py`, `bdf_mass_extractor.py`
+- via validation/intake/wizard/base runner.
+
+Used mainly by studies/tools/dashboard:
+- `extract_frequency.py`, `extract_mass_from_expression.py`, `extract_zernike*.py`, `op2_extractor.py`, `stiffness_calculator.py`.
+
+Likely orphaned (no non-test references found):
+- `field_data_extractor.py`
+- `zernike_helpers.py`
+
+Low-usage / isolated:
+- `extract_stress_field_2d.py` (single tools reference)
+- `extract_zernike_surface.py` (single study script reference)
+
+## 5.3 Orphaned module references (hard breaks)
+
+- Missing module imports in code:
+  - `optimization_engine.extractor_orchestrator` (missing)
+  - `optimization_engine.inline_code_generator` (missing)
+  - `optimization_engine.hook_generator` (missing)
+  - `optimization_engine.study_runner` (missing)
+
+Evidence:
+- `optimization_engine/future/llm_optimization_runner.py:26-28`
+- `optimization_engine/config/setup_wizard.py:26-27`
+- generated script template in `optimization_engine/config/template_loader.py:216`
+
+## 6) Hooks/Plugins: Wired vs Scaffolding
+
+There are **two distinct hook concepts**:
+
+1. `optimization_engine/plugins/*`:
+- lifecycle hook framework (`pre_solve`, `post_solve`, etc.) used by runners.
+
+2. `optimization_engine/hooks/*`:
+- NX Open CAD/CAE API wrappers (not plugin lifecycle hooks).
+
+### What is actually wired
+- `core/runner.py` executes hook points across trial lifecycle.
+- `future/llm_optimization_runner.py` also executes lifecycle hooks.
+
+### Why most plugins are not actually loaded
+- Wrong plugin directory resolution:
+  - `core/runner.py:76` uses `Path(__file__).parent / 'plugins'` -> `optimization_engine/core/plugins` (does not exist).
+  - `future/llm_optimization_runner.py:140` uses `optimization_engine/future/plugins` (does not exist).
+  - `config/setup_wizard.py:426` same issue (`optimization_engine/config/plugins`).
+- Real plugin directory is `optimization_engine/plugins/`.
+
+### Additional plugin scaffolding mismatches
+- Hook point enum uses `custom_objective` (`plugins/hooks.py:24`) but directory present is `plugins/custom_objectives/` (plural).
+- `safety_factor_constraint.py` defines `register_hooks` but returns `[hook]` without calling `hook_manager.register_hook(...)` (`plugins/post_calculation/safety_factor_constraint.py:88-90`), so loader does not register it.
+
+Net: hook execution calls exist, but effective loaded-hook count is often zero.
+
+## 7) Data Flow Through Actual Code
+
+## 7.1 `atomizer.py` main flows
+
+1. `neural-optimize`:
+- validate study via `validators.study_validator`
+- inspect training state via `AutoTrainer`
+- subprocess into `studies/<study>/run_optimization.py`
+- optional post-run retraining
+
+2. `intake`:
+- `IntakeProcessor` populates context, introspection, baseline
+
+3. `gate`:
+- `ValidationGate` validates spec + optional test trials + extractor probes
+
+4. `finalize`:
+- `HTMLReportGenerator` builds report
+
+## 7.2 `optimization_engine/run_optimization.py` intended flow
+
+- Parse args -> validate `prt/sim`
+- `--llm`: analyze request -> setup updater/solver closures -> `LLMOptimizationRunner` -> Optuna loop
+- `--config`: currently stub that exits
+
+Actual current behavior: import-time crash before step 1.
+
+## 8) High-Risk Inconsistencies Blocking Migration
+
+- Broken import namespace split between `future/*` and expected top-level modules.
+- Template system points to wrong template/study roots and generates scripts importing missing `study_runner`.
+- Hook framework looks complete but plugin discovery paths are wrong in all main call sites.
+- `atomizer` delegates execution to many inconsistent study-local scripts, preventing predictable architecture.
+

war-room-migration-plan.md

@@ -0,0 +1,206 @@
+# War-Room Migration Plan (Prioritized, Code-Level)
+
+Date: 2026-02-20
+Goal: Stabilize entrypoints and create a coherent, testable architecture from the current code reality.
+
+## Phase 0 - Stop The Bleeding (P0, 1-2 days)
+Risk: High if skipped, Low implementation risk
+
+Moves:
+- Fix broken module import paths in runtime code:
+  - `optimization_engine/future/llm_optimization_runner.py`
+  - `optimization_engine/config/setup_wizard.py`
+- Make `optimization_engine/run_optimization.py` importable/executable.
+- Fix plugin directory resolution in all loaders:
+  - `core/runner.py`
+  - `future/llm_optimization_runner.py`
+  - `config/setup_wizard.py`
+
+Interface changes:
+- None to user CLI shape.
+- Internal module paths become explicit (`optimization_engine.future.*` or extracted to a new stable package).
+
+Dependency order:
+1. Fix import paths.
+2. Fix plugin discovery path.
+3. Add smoke tests for `atomizer.py --help` and `optimization_engine/run_optimization.py --help`.
+
+Concrete refactor steps:
+1. Replace missing imports with real module paths:
+   - `optimization_engine.extractor_orchestrator` -> `optimization_engine.future.extractor_orchestrator`
+   - `optimization_engine.inline_code_generator` -> `optimization_engine.future.inline_code_generator`
+   - `optimization_engine.hook_generator` -> `optimization_engine.future.hook_generator`
+2. In hook loaders, resolve plugin root to `optimization_engine/plugins` (shared constant helper).
+3. Add assertion/telemetry when no hooks are loaded to avoid silent no-op behavior.
+
+## Phase 1 - Entrypoint Contract Unification (P0, 2-4 days)
+Risk: Medium
+
+Moves:
+- Define a single canonical optimization runner API used by both:
+  - `atomizer.py` workflows
+  - `optimization_engine/run_optimization.py`
+- Remove dead import (`OptimizationRunner`) from unified runner unless actually used.
+- Implement manual mode or explicitly remove it behind feature flag.
+
+Interface changes:
+- Introduce a stable internal entry function, e.g. `optimization_engine.app.run(spec)`.
+- Keep CLI flags backward-compatible in this phase.
+
+Dependency order:
+1. Stabilize Phase 0.
+2. Create adapter layer from old study scripts to new runner API.
+3. Route `run_optimization.py` through this API.
+
+Concrete refactor steps:
+1. Create `optimization_engine/app/runner_service.py` with:
+   - config parsing
+   - model update/solve/extract loop
+   - hook execution
+2. Convert `run_optimization.py` to thin CLI adapter.
+3. Add compatibility wrapper for existing study scripts.
+
+## Phase 2 - Study Script Decoupling (P1, 1-2 weeks)
+Risk: High (behavioral)
+
+Moves:
+- Stop subprocess dependence on arbitrary `studies/<study>/run_optimization.py` from `atomizer.py`.
+- Replace with deterministic “load study spec + run canonical engine”.
+
+Interface changes:
+- `atomizer neural-optimize --study X` resolves study metadata and calls canonical engine directly.
+- Study-local scripts become optional wrappers, not required runtime dependency.
+
+Dependency order:
+1. Canonical runner available (Phase 1).
+2. Study resolver module.
+3. Migrate one or two representative studies first (UAV + M1 mirror).
+
+Concrete refactor steps:
+1. Implement study resolver for `1_setup/optimization_config.json` and/or `atomizer_spec.json`.
+2. Add `atomizer` path for direct in-process execution.
+3. Keep fallback to legacy script for unmigrated studies with explicit warning.
+
+## Phase 3 - Hooks/Plugins Hardening (P1, 3-5 days)
+Risk: Medium
+
+Moves:
+- Consolidate lifecycle hook system (`plugins`) and clarify that NX Open wrappers (`hooks`) are separate.
+- Fix mismatches:
+  - `custom_objective` hook point vs `custom_objectives` folder naming.
+  - broken plugin registration patterns (e.g. return list without registering).
+
+Interface changes:
+- Standard plugin authoring contract:
+  - `register_hooks(hook_manager) -> None`
+  - must call `hook_manager.register_hook(...)`
+
+Dependency order:
+1. Shared plugin root helper.
+2. Plugin validation lint.
+3. Hook contract docs + tests.
+
+Concrete refactor steps:
+1. Add plugin linter test to fail on non-registered plugins.
+2. Normalize folder naming to enum values.
+3. Add runtime summary printout for loaded/active hooks at each hook point.
+
+## Phase 4 - Extractor Surface Rationalization (P1, 1 week)
+Risk: Medium
+
+Moves:
+- Classify extractors into tiers:
+  - Tier A (active runtime): displacement/stress/mass/frequency basics
+  - Tier B (domain-specific): zernike, optical, special studies
+  - Tier C (candidate deprecate): no references (`field_data_extractor.py`, `zernike_helpers.py`)
+- Move tier C to `archive/` or mark deprecated.
+
+Interface changes:
+- New extractor registry metadata: status (`active`, `experimental`, `deprecated`).
+
+Dependency order:
+1. Build reference report snapshot.
+2. Mark deprecated modules.
+3. Remove only after one release cycle.
+
+Concrete refactor steps:
+1. Add machine-readable registry file for extractors.
+2. Enforce registration for runtime-eligible extractors.
+3. Update callers to consume registry, not free-form imports.
+
+## Phase 5 - Template/Study Generation Repair (P1, 2-4 days)
+Risk: Medium
+
+Moves:
+- Fix template loader roots and generated script imports.
+- Current issues:
+  - templates resolve to `optimization_engine/templates` instead of repo `templates/` JSON set.
+  - studies root points to missing `optimization_engine/studies`.
+  - generated scripts import missing `optimization_engine.study_runner`.
+
+Interface changes:
+- `atomizer create-study` should generate runnable study directly against canonical runner API.
+
+Dependency order:
+1. Canonical runner available (Phase 1).
+2. Replace generated script template.
+3. Add integration test for create+validate flow.
+
+Concrete refactor steps:
+1. Correct template/study root resolution to repo-level paths.
+2. Replace `study_runner` import with canonical service call.
+3. Validate generated study with `atomizer validate` in CI smoke test.
+
+## Phase 6 - Future Folder Re-homing (P2, 1 week)
+Risk: Low/Medium
+
+Moves:
+- Split `optimization_engine/future/` into:
+  - `experimental/` (not production-wired)
+  - `runtime/` (production-wired)
+- Remove deprecation aliases from `optimization_engine/__init__.py` that point to non-runtime pieces unless intentionally supported.
+
+Interface changes:
+- Explicit import policy: production code cannot import `experimental` without feature flag.
+
+Dependency order:
+1. Tag modules by runtime usage.
+2. Move files and add shims.
+3. Remove shims after transition window.
+
+Concrete refactor steps:
+1. Create `optimization_engine/experimental/`.
+2. Move low-usage research modules.
+3. Keep only proven runtime modules in primary namespace.
+
+## Phase 7 - Verification and Guardrails (P0 ongoing)
+Risk: High if omitted
+
+Moves:
+- Add CI checks that would have caught current breakage:
+  - import smoke for both entrypoints
+  - plugin load count assertions
+  - create-study runnable check
+
+Concrete refactor steps:
+1. Add tests:
+   - `test_entrypoint_imports.py`
+   - `test_plugin_discovery_paths.py`
+   - `test_template_loader_paths.py`
+2. Add static scan that fails on unresolved `optimization_engine.<module>` imports.
+3. Add architecture decision record (ADR) for canonical runner + plugin model.
+
+## Dependency-Critical Ordering Summary
+1. Phase 0 (import/plugin path fixes)
+2. Phase 1 (canonical runner contract)
+3. Phase 2 and 5 (atomizer/study generation migration)
+4. Phase 3 (hooks hardening)
+5. Phase 4 and 6 (extractor/future rationalization)
+6. Phase 7 continuously
+
+## Quick Wins (do immediately)
+1. Fix `run_optimization.py` import crash.
+2. Fix all three plugin loader paths.
+3. Remove or wire `OptimizationRunner` import in unified runner.
+4. Fix `template_loader` roots and `study_runner` reference.
+