Atomizer/hq/workspaces/shared/reviews/v2-migration-coherence-audit.md

# Cross-Document Coherence Audit — V2 Migration Pre-Flight
**Date:** 2026-02-23  
**Auditor:** Auditor (Subagent)  
**Documents Reviewed:** 5 source document sets, 48 AOM docs (sampled), 4 pillars  
**Scope:** Pre-migration alignment verification for Atomizer V2 migration

---

## Executive Summary

**VERDICT: CONDITIONAL PASS — Proceed with Cautions**

The V2 migration can proceed, but **not as-is**. Three critical contradictions and five major gaps require resolution before Phase 1 execution. The documents are directionally aligned on architecture and tool strategy, but they diverge on:

1. **Contracts implementation timing** (contradictory)
2. **Project Standard integration scope** (under-specified in Arsenal V3)
3. **Structural path definitions** (contradictions between Arsenal V3 and Migration Plan V3.1)

### Top 3 Findings

| # | Finding | Severity | Impact |
|---|---------|----------|--------|
| 1 | **Contracts deferral conflict:** Arsenal V3 says "contracts are canonical in architecture doc," Migration Plan V3.1 says "stubs only at P0, implement post-migration" — Architecture doc says "contracts are NEW" (not existing). This creates a circular dependency. | 🔴 CRITICAL | Phase 1 cannot implement contracts that don't exist yet |
| 2 | **Project Standard orphaned in Arsenal V3:** Migration Plan V3.1 added full Project Standard integration (§5.5, templates/, init script) as P1 deliverables. Arsenal V3 Final (the architecture source) doesn't mention Project Standard at all — no templates folder, no init script, no study paths at `03-studies/`. | 🔴 CRITICAL | Arsenal V3 is not the complete architecture — migration plan adds 15+ deliverables not defined upstream |
| 3 | **NX consolidation path mismatch:** Arsenal V3 says `atomizer/processors/geometry/nx_geometry.py`, Migration V3 says `atomizer/nx/` as consolidated NX home with journals/ subdirectory. Both are present in V2 structure tree but with different organizational philosophies. | 🟡 MAJOR | NX code may be split across two locations creating maintenance confusion |

### Recommendation

**APPROVE migration with mandatory pre-Phase-1 actions:**

1. **Resolve contracts chicken-and-egg:** Either (a) write contract stub definitions NOW in architecture doc before migration starts, OR (b) accept that contracts are post-migration work and remove all P0/P1 references to implementing them
2. **Backport Project Standard to Arsenal V3:** Update Arsenal V3 Final (the canonical architecture) to include Project Standard as a first-class component with templates/, init script, and engine --project-root support
3. **Consolidate NX strategy:** CEO decision: Is NX a processor alongside others (`processors/geometry/nx_geometry.py`) OR is it a special legacy subsystem (`nx/` with all NX code consolidated)? Both structures exist in the plan — pick one.

With these three corrections, the migration is **sound and executable**.

---

## A. Structural Alignment

**Question:** Does the V2 repo structure in the migration plan match what Arsenal V3 defines?

### Alignment ✅

| Component | Arsenal V3 Final | Migration Plan V3.1 | Status |
|-----------|------------------|---------------------|--------|
| Three-layer architecture | `contracts/`, `processors/`, `orchestrator/` | ✅ Present in V2 tree | ✅ MATCH |
| Optimization engine | `atomizer/optimization/` | ✅ Present | ✅ MATCH |
| Extractors | `atomizer/extractors/` | ✅ Present | ✅ MATCH |
| Spec/config | `atomizer/spec/` | ✅ Present | ✅ MATCH |
| Dashboard | `dashboard/` | ✅ Present | ✅ MATCH |
| MCP servers | `mcp_servers/` | ✅ Present (placeholder) | ✅ MATCH |
| Knowledge base | `atomizer/knowledge/` | ✅ Present | ✅ MATCH |

### Contradictions 🔴

| Item | Arsenal V3 Says | Migration Plan V3.1 Says | Resolution Needed |
|------|----------------|-------------------------|-------------------|
| **Contracts location** | "Canonical in `ATOMIZER-TOOL-AGNOSTIC-ARCHITECTURE.md` Section 2.1" (Arsenal V3 §2.1–2.2) | `atomizer/contracts/*.py` files in V2 tree (§2) | ⚠️ **Problem:** Architecture doc (from AOM review) says contracts are NEW design, not existing code. Arsenal says "don't duplicate dataclass definitions" but doesn't provide them. Migration says "stub → implement P1/P2" but Arsenal says "these are canonical already." **CIRCULAR DEPENDENCY.** |
| **NX module organization** | `atomizer/processors/geometry/nx_geometry.py` (Arsenal V3 §4.1 table) | `atomizer/nx/` with `solver.py`, `session_manager.py`, `journals/`, etc. (Migration §2, §3.7) | ⚠️ Arsenal treats NX as one processor among many. Migration treats NX as a special subsystem. Both exist in V2 tree. **SPLIT PERSONALITY.** |
| **Project Standard templates** | ❌ NOT MENTIONED in Arsenal V3 | `templates/project/` + `tools/init_project.py` + engine `--project-root` flag (Migration §2, §3.17, §5.5) | ⚠️ **Arsenal V3 is incomplete.** Migration added ~15 files and integration work that Arsenal never defined. |

### Gaps 🟡

| Gap | Arsenal Defines | Migration Implements | Missing Link |
|-----|----------------|---------------------|--------------|
| **processors/base.py** | Arsenal V3 §4.1: "Abstract base classes (NEW)" | Migration §2: `atomizer/processors/base.py` | ✅ Implied by Arsenal, implemented by Migration — no gap |
| **orchestrator/pipeline.py** | Arsenal V3 §4.1: "Main evaluation loop" (NEW) | Migration §2: `atomizer/orchestrator/pipeline.py` | ✅ Implied by Arsenal, implemented by Migration |
| **Processor categories** | Arsenal V3 lists: geometry/, meshing/, solvers/, postprocessing/, converters/, surrogates/ | Migration §2 has all 6 categories | ✅ Full alignment |

### Naming Consistency ✅

Folder names, module locations, and component boundaries are **consistent** where both documents define them. The contradictions are about *what's included*, not *what it's called*.

**Verdict for Section A: 🟡 MAJOR ISSUES**
- Core architecture alignment is strong (3-layer model, folder structure, component names)
- Contracts and NX placement are contradictory
- Project Standard is a migration-only addition not backed by Arsenal

---

## B. Project Standard Integration

**Question:** Does the migration plan properly implement the Project Standard's folder structure, entry points, KB architecture, and study lifecycle?

### What the Project Standard Defines

From `P-Atomizer-Project-Standard/05-FINAL-RECOMMENDATION.md`:

| Requirement | Specification |
|-------------|--------------|
| **Root structure** | 9 top-level items: README, CONTEXT, BREAKDOWN, DECISIONS, models/, kb/, studies/, playbooks/, deliverables/ |
| **Study numbering** | `{NN}_{slug}` format (01_doe_landscape, 02_tpe_refined, etc.) |
| **KB structure** | 4 folders: components/, materials/, fea/, dev/ |
| **Study lifecycle** | 3 phases: Setup (human) → Execute (machine) → Review (human+machine) |
| **Study internals** | 1_setup/, 2_iterations/, 3_results/, 3_insights/ |
| **Entry points** | README.md (single entry, not PROJECT+AGENT+STATUS split) |

### What Migration Plan V3.1 Implements

From Migration Plan §3.17, §5.5:

| Component | Migration Status | Location |
|-----------|-----------------|----------|
| **Template files** | ✅ ~14 .template files | `templates/project/` |
| **Scaffolding script** | ✅ NEW script | `tools/init_project.py` |
| **Engine integration** | ✅ `--project-root` flag | `atomizer/optimization/engine.py`, `atomizer/study/creator.py` |
| **AOM reference** | ✅ Pillar 2 cross-reference planned | `docs/AOM/02-Operations/` |

### Does Migration Match Project Standard?

| Project Standard Requirement | Migration Plan Implementation | Status |
|-------------------------------|------------------------------|--------|
| **9-item root structure** | Template includes PROJECT.md, AGENT.md, STATUS.md, DECISIONS.md, CHANGELOG.md, 00-context/, 01-models/, 02-kb/, 03-studies/, etc. | ⚠️ **MISMATCH:** Standard recommends **single README.md**, not PROJECT+AGENT+STATUS split. Migration uses OLD spec structure (§9 of spec superseded by §5 final recommendation). |
| **KB 4-folder structure** | Template has design/ (5 branches), analysis/ (7 subdirs), manufacturing/, domain/, introspection/ | 🔴 **CONTRADICTION:** Standard says 4 folders (components/, materials/, fea/, dev/). Template has **5 branches with 15+ subdirs** (the OLD rejected spec). |
| **Study lifecycle** | Engine integration supports `--project-root`, studies at `03-studies/` | ✅ MATCH |
| **Study numbering** | Standard: `{NN}_{slug}`. Engine: compatible | ✅ MATCH |
| **atomizer_spec.json** | Standard: per-study spec at study root. Engine: loads from study path | ✅ MATCH |

### Critical Finding 🔴

**The Migration Plan's Project Standard templates (§3.17 table) are based on the REJECTED SPECIFICATION (00-SPECIFICATION.md), NOT the APPROVED FINAL RECOMMENDATION (05-FINAL-RECOMMENDATION.md).**

Evidence:
- Final Recommendation says: "README.md (single entry point, replaces PROJECT+AGENT+STATUS)"
- Migration template table lists: "PROJECT.md.template, AGENT.md.template, STATUS.md.template"
- Final Recommendation says: "KB 4 folders (components/, materials/, fea/, dev/)"
- Migration template structure shows: "design/, analysis/ with 7 subdirs, manufacturing/, domain/, introspection/"

**The migration is implementing the WRONG standard.**

### Gaps 🟡

| Gap | Description |
|-----|-------------|
| **Template versioning** | Project Standard spec §9 calls for `.atomizer/template-version.json` to track which standard version a project uses. Migration lists this file but doesn't specify version tagging strategy. |
| **Migration script for existing projects** | Standard discusses migrating Hydrotech Beam (~15 min effort). Migration plan doesn't include a migration helper for V1 projects to Project Standard structure. |

**Verdict for Section B: 🔴 CRITICAL FAILURE**
- Migration implements the **rejected spec**, not the **approved recommendation**
- Templates must be completely rewritten before Phase 1
- This affects ~15 files in the migration inventory (§3.17)

---

## C. AOM Consistency

**Question:** Does the migration plan's documentation structure align with the AOM's 4-pillar organization? Would migration break AOM references?

### AOM Structure (from MAP.md)

| Pillar | Docs | Purpose |
|--------|------|---------|
| 01-Philosophy | 9 docs | Mission, architecture, component map, tool-agnostic design |
| 02-Operations | 15 docs | Study lifecycle, protocols, specs, integrations |
| 03-Developer | 10 docs | Codebase, API, extension points, processor dev |
| 04-Knowledge | 6 docs | LAC, KB architecture, failure patterns |

**Total:** 48 docs (40 main docs + Audit/ + Phase-4-LLM-Layer/ + Phase-5-Living-Protocol/)

### Migration Plan's AOM Deployment

From Migration §5:

```
docs/
├── AOM/
│   ├── README.md                  # MAP (renamed)
│   ├── 01-Philosophy/             # 9 docs
│   ├── 02-Operations/             # 15 docs
│   ├── 03-Developer/              # 10 docs
│   ├── 04-Knowledge/              # 6 docs
│   └── Audit/                     # 2 docs
├── protocols/                     # OP/SYS/EXT migrated from V1
├── QUICK_REF.md
└── guides/
```

**Alignment:** ✅ **PERFECT 1:1 MAPPING**

The migration preserves the exact 4-pillar structure. MAP.md → README.md rename is correct (Gitea auto-renders README).

### Path Breakage Check

**Question:** Do any AOM docs reference V1 paths that the migration would break?

Sample from AOM docs reviewed:
- Component Map (§4) references `atomizer/contracts/`, `atomizer/processors/`, `atomizer/orchestrator/` → ✅ These paths exist in V2 structure
- Tool-Agnostic Architecture (§8) describes the 3-layer model → ✅ V2 implements this exactly
- Arsenal Reference would reference MCP servers → ✅ `mcp_servers/` placeholder exists in V2

**Potential Breaks:**

| AOM Doc | Likely References | V2 Status | Risk |
|---------|-------------------|-----------|------|
| 02-Operations/09-NX-Integration | May reference `optimization_engine/nx/` paths | ⚠️ V2 has `atomizer/nx/` — paths changed | 🟡 Needs path updates |
| 03-Developer/01-Codebase-Architecture | Module dependency map | ⚠️ All `optimization_engine.*` → `atomizer.*` | 🟡 Needs update |
| 03-Developer/03-API-Reference | Import statements | ⚠️ Import paths changed | 🟡 Needs update |
| 04-Knowledge/02-Knowledge-Base-Architecture | May reference old `knowledge_base/` | ✅ V2 has `atomizer/knowledge/` | ✅ Compatible if relative |

**Mitigation:** Migration Phase 0 includes AOM link conversion (§5.1: convert `[[wiki-links]]` → relative MD links). This MUST also update any code paths in AOM docs from `optimization_engine/` → `atomizer/`.

### AOM Cross-References to Project Standard

Migration §5.5.4 says: "AOM Pillar 2 (Operations) references the Project Standard spec"

**Gap:** The AOM MAP.md reviewed does NOT currently mention Project Standard. The only reference is in Related Projects section pointing to `P-Atomizer-Project-Standard/MAP`.

**Required action:** During AOM deployment (Phase 0), add Project Standard guide to `02-Operations/` (e.g., `02-Operations/16-Project-Organization-Standard.md` or update existing docs to reference templates/).

**Verdict for Section C: 🟢 OK with Minor Updates**
- AOM pillar structure perfectly preserved
- Path updates needed in 3–5 AOM docs (tracked in Phase 0)
- Project Standard cross-reference is a forward commitment, not a current contradiction

---

## D. Contradictions Table

| Doc1 Says | Doc2 Says | Nature | Severity |
|-----------|-----------|--------|----------|
| **Arsenal V3 §2.2:** "Contract dataclasses are canonical in `ATOMIZER-TOOL-AGNOSTIC-ARCHITECTURE.md` Section 2.1. Do not duplicate." | **Tool-Agnostic Architecture (AOM):** Contracts are described as NEW design pattern. Section 2.1 lists what they should contain but doesn't provide Pydantic/dataclass implementations. | Contracts don't exist yet, but Arsenal references them as canonical source. | 🔴 CRITICAL |
| **Arsenal V3 §2.2:** "All contract details reference Section 2.1 above" (implying contracts are defined) | **Migration V3.1 §2, Phase 1:** "Create contract stubs (docstrings only, no implementation). DEFERRED to post-migration." | Arsenal says contracts exist. Migration says create stubs. Circular dependency. | 🔴 CRITICAL |
| **Arsenal V3 §4.1:** NX listed as `atomizer/processors/geometry/nx_geometry.py` | **Migration §2 + §3.7:** NX consolidated at `atomizer/nx/` with `solver.py`, `session_manager.py`, `journals/` | Is NX a single geometry processor or a subsystem? | 🟡 MAJOR |
| **Arsenal V3 Sprint 3 §5.3:** "Topology Engineer (new)" activated Sprint 3 | **Webster Review §4:** "Topology is post-MVP future (Arsenal V3 §3.1). Role activation conflicts with scope boundary." | Topology Engineer exists in agent roster but topology is explicitly out of scope. | 🟡 MAJOR |
| **Project Standard Final Recommendation:** "README.md (single entry point)" | **Migration §3.17 template table:** "PROJECT.md.template + AGENT.md.template + STATUS.md.template" | Migration implements rejected spec, not approved recommendation. | 🔴 CRITICAL |
| **Project Standard Final Recommendation:** "4-folder KB: components/, materials/, fea/, dev/" | **Migration §3.17 template structure:** "design/ → analysis/ (7 subdirs) → manufacturing/ → domain/ → introspection/" | Migration uses OLD 5-branch spec rejected by final recommendation. | 🔴 CRITICAL |
| **Arsenal V3 §3.1:** OpenFOAM is "Expansion Stack (Sprints 4-6)" | **Arsenal V3 §5.4:** Sprint 4 delivers OpenFOAM lane | ✅ Self-consistent — expansion starts Sprint 4 | 🟢 OK |
| **Arsenal V3 §4.1:** `launch_dashboard.py` listed in root | **Migration §2:** `dashboard/launch_dashboard.py` | Path moved — minor | 🟢 OK |

**Summary:** 3 critical contradictions, 2 major contradictions, 0 architecture-breaking contradictions (the core 3-layer model is fully aligned).

---

## E. Gaps Table

### Defined in Source, Missing from Migration

| Defined In | What's Defined | Missing From | Impact |
|------------|---------------|--------------|--------|
| Arsenal V3 §6 (Agent Roster) | 19 agents: Manager, Technical Lead, Optimizer, NX Expert, Post-Processor, Reporter, Study Builder, Auditor, Researcher, Developer, KB, IT, **Meshing Engineer, CFD Specialist, Coupling Engineer, Topology Engineer, MDO Architect, MCP Engineer**, Secretary | Migration Plan (repo structure) | 🟢 OK — agents are runtime entities, not repo structure. Migration doesn't need to define agents. |
| Arsenal V3 §8 (MCP Servers) | Top 4 MCP servers: MCP-CalculiX, MCP-Gmsh, MCP-Build123d, MCP-pyNastran | Migration §2 | 🟡 **GAP:** Migration has `mcp_servers/` placeholder but no implementation plan or file inventory. Should list README.md at minimum. |
| Tool-Agnostic Architecture (AOM) | Abstract base classes: `SolverProcessor`, `GeometryProcessor`, `MeshProcessor` with specific method signatures | Migration §2 | ✅ Migration says "Create `atomizer/processors/base.py`" — covered. |
| Arsenal V3 §2.3 (AOM Placement) | "All implementation mapping lands inside V2 repo paths under atomizer/contracts/, processors/, orchestrator/, optimization/, mcp_servers/" | Migration Plan V2 tree | ✅ V2 tree includes all 5 paths. Full alignment. |
| Project Standard spec §3 (Study Internals) | Study folder structure: `1_setup/`, `2_iterations/`, `3_results/`, `3_insights/` | Migration Plan, Arsenal V3 | 🟡 **GAP:** Neither Arsenal nor Migration describes study internals structure. Project Standard defines it, but no one implements engine support for `1_setup/model/` copying or `3_insights/` auto-generation. |

### Defined in Migration, Not in Source

| Migration Defines | Source Coverage | Gap Type |
|------------------|----------------|----------|
| **Project Standard templates (~15 files)** | ❌ Not in Arsenal V3. Not in AOM (yet). In separate spec doc only. | 🔴 **CRITICAL:** Arsenal V3 is supposed to be the canonical architecture. It's incomplete. |
| **`atomizer/_compat.py` import shim** | ❌ Not in Arsenal V3 | 🟢 OK — migration-specific transition tool, not architecture |
| **`tools/init_project.py` scaffolding script** | ❌ Not in Arsenal V3 | 🔴 **MAJOR:** If Project Standard is first-class (per Migration §5.5), Arsenal should define this. |
| **`--project-root` engine flag** | ❌ Not in Arsenal V3 | 🔴 **MAJOR:** Needed for Project Standard study paths. Not in architecture spec. |
| **Phase-by-phase rollback procedures (Migration §16)** | ❌ Not in Arsenal V3 or Webster Review | 🟢 OK — operational concern, not architecture |
| **Pre-commit hooks config (Migration §13)** | ❌ Not in Arsenal V3 | 🟢 OK — repo hygiene, not architecture |

**Summary:** 5 major gaps. The biggest: Arsenal V3 doesn't define Project Standard integration, but Migration treats it as first-class architecture.

---

## F. Naming & Path Consistency

**Question:** Do all documents use consistent naming for modules, folders, and components?

### Folder/Module Names ✅

| Component | Arsenal V3 | Migration V3.1 | AOM (Component Map) | Consistent? |
|-----------|------------|---------------|---------------------|-------------|
| Contracts | `atomizer/contracts/` | `atomizer/contracts/` | `atomizer/contracts/` | ✅ |
| Processors | `atomizer/processors/` | `atomizer/processors/` | `atomizer/processors/` | ✅ |
| Orchestrator | `atomizer/orchestrator/` | `atomizer/orchestrator/` | `atomizer/orchestrator/` | ✅ |
| Optimization | `atomizer/optimization/` | `atomizer/optimization/` | `atomizer/optimization/` | ✅ |
| Extractors | `atomizer/extractors/` | `atomizer/extractors/` | `atomizer/extractors/` | ✅ |
| Spec/Config | `atomizer/spec/` | `atomizer/spec/` | `atomizer/spec/` | ✅ |
| Knowledge | `atomizer/knowledge/` | `atomizer/knowledge/` | `atomizer/knowledge/` | ✅ |
| Dashboard | `dashboard/` | `dashboard/` | `dashboard/` | ✅ |
| MCP Servers | `mcp_servers/` | `mcp_servers/` | `mcp_servers/` | ✅ |

**Naming is 100% consistent** where all documents define the same component.

### Module Renaming Consistency ✅

| V1 Name | V2 Name (Arsenal) | V2 Name (Migration) | Consistent? |
|---------|------------------|---------------------|-------------|
| `optimization_engine/core/runner.py` | `atomizer/optimization/engine.py` | `atomizer/optimization/engine.py` | ✅ |
| `optimization_engine/extractors/extractor_library.py` | `atomizer/extractors/registry.py` | `atomizer/extractors/registry.py` | ✅ |
| `optimization_engine/config/` | `atomizer/spec/` | `atomizer/spec/` | ✅ |

### Component Terminology ✅

| Concept | Arsenal V3 | Migration V3.1 | AOM | Consistent? |
|---------|------------|---------------|-----|-------------|
| Universal data types | "Contracts" | "Contracts" | "Data Contracts" | ✅ |
| Tool-specific translators | "Processors" | "Processors" | "Processors" | ✅ |
| Pipeline controller | "Orchestrator" | "Orchestrator" | "Orchestrator" | ✅ |
| Study configuration | "AtomizerSpec v3.0" | "AtomizerSpec v3.0" | "AtomizerSpec" | ✅ |
| Optimization algorithms | "Optuna/pymoo/OpenMDAO" | "Optuna/pymoo" | "Optuna/pymoo" | ✅ |

### Inconsistencies 🟡

| Inconsistency | Where | Impact |
|--------------|-------|--------|
| **NX placement** | Arsenal: `processors/geometry/nx_geometry.py`. Migration: `atomizer/nx/` (full module) + `processors/geometry/nx_geometry.py` (also listed in tree §2). | 🟡 MAJOR — both exist in V2 tree, unclear which is canonical |
| **Surrogates location** | Arsenal: `processors/surrogates/` (9 files). Migration also has `optimization/surrogates/` (GNN). Both exist. | 🟡 MINOR — Tech Lead noted this in V3 review. Need docstring clarification or consolidation. |

**Verdict for Section F: 🟢 GOOD**
- 99% naming consistency across all documents
- NX placement ambiguity is the only significant issue (same as structural alignment finding)

---

## Recommendations (Prioritized)

### 🔴 CRITICAL (Blockers — Must Fix Before Phase 1)

| # | Recommendation | Affected Phases | Effort |
|---|---------------|----------------|--------|
| C1 | **Resolve contracts chicken-and-egg:** Write contract stub definitions in Tool-Agnostic Architecture doc (AOM Pillar 1) NOW, before migration starts. Provide at minimum: class signatures, field lists, docstrings. OR accept contracts are post-migration and remove them from Phase 1 scope entirely. | Phase 0, Phase 1 | 🕐 4 hours (write stubs) |
| C2 | **Rewrite Project Standard templates:** The current template list (Migration §3.17) implements the REJECTED spec. Rewrite all 14 templates to match the APPROVED Final Recommendation: single README.md (not PROJECT+AGENT+STATUS), 4-folder KB (not 5-branch). | Phase 1 | 🕐🕐 8 hours (rewrite 14 templates) |
| C3 | **Backport Project Standard to Arsenal V3:** Update Arsenal V3 Final to include Project Standard as a first-class component. Add: templates/ folder, init script, --project-root flag, study path conventions. Arsenal must be the complete architecture source. | Pre-Phase 0 | 🕐🕐 6 hours (update Arsenal doc) |

### 🟡 MAJOR (High Priority — Resolve in Phase 0 or Phase 1)

| # | Recommendation | Affected Phases | Effort |
|---|---------------|----------------|--------|
| M1 | **Consolidate NX strategy:** CEO decision required. Is NX (a) a processor like any other (`processors/geometry/nx_geometry.py` only), OR (b) a special legacy subsystem (`atomizer/nx/` with all NX code including journals/). Remove one or clearly document why both exist. | Phase 1 | 🕐 2 hours (decide + update docs) |
| M2 | **Update AOM code paths:** During Phase 0 AOM deployment, update 3–5 AOM docs that reference `optimization_engine/` paths → `atomizer/`. Specifically: 02-Operations/09-NX-Integration, 03-Developer/01-Codebase-Architecture, 03-Developer/03-API-Reference. | Phase 0 | 🕐 2 hours |
| M3 | **Add Project Standard reference to AOM:** Create `docs/AOM/02-Operations/16-Project-Organization-Standard.md` explaining the template system, init script, and --project-root integration. Cross-reference from Study Lifecycle doc. | Phase 0 | 🕐 3 hours |
| M4 | **Clarify study internals implementation:** Project Standard defines `1_setup/`, `2_iterations/`, `3_results/`, `3_insights/` study structure. Migration assumes engine supports this but doesn't specify implementation. Verify `atomizer/study/creator.py` creates this structure, or add to Phase 1 scope. | Phase 1 | 🕐 4 hours (code + verify) |
| M5 | **Document MCP server scope:** Arsenal V3 says top 4 MCP servers (CalculiX, Gmsh, Build123d, pyNastran) are MVP. Migration has `mcp_servers/` placeholder. Add `mcp_servers/README.md` with implementation roadmap, or explicitly defer to post-MVP. | Phase 0 or Phase 2 | 🕐 1 hour (README) |

### 🟢 MINOR (Nice to Have — Address During Migration)

| # | Recommendation | Effort |
|---|---------------|--------|
| N1 | **Topology Engineer activation:** Arsenal activates Topology Engineer in Sprint 3, but topology is post-MVP. Either defer activation or scope role to "benchmark prep only" as Webster suggested. | 🕐 30 min (update agent roster) |
| N2 | **Surrogates consolidation:** `processors/surrogates/` and `optimization/surrogates/` both exist. Add docstring to each `__init__.py` explaining the distinction (processors = classical ML, optimization = GNN). Or consolidate if redundant. | 🕐 1 hour |
| N3 | **Template versioning strategy:** `.atomizer/template-version.json` exists in template list but versioning scheme is undefined. Define format: `{"standard_version": "1.0.0", "deployed_date": "2026-02-23"}`. | 🕐 30 min |

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|-----------|
| **Contracts undefined causes Phase 1 failure** | HIGH (if not fixed) | CRITICAL | C1: Write stubs NOW or defer contracts |
| **Wrong Project Standard templates deployed** | HIGH (templates are wrong) | CRITICAL | C2: Rewrite templates before Phase 1 |
| **NX code fragmentation** | MEDIUM | MAJOR | M1: Consolidate before Phase 1 |
| **AOM paths broken after migration** | MEDIUM | MAJOR | M2: Update during Phase 0 |
| **Study structure assumptions break** | MEDIUM | MAJOR | M4: Verify engine implementation |
| **Arsenal V3 incomplete as architecture source** | MEDIUM | MAJOR | C3: Backport Project Standard |

---

## Verification Checklist (for CEO/Manager)

Before approving Phase 0 start:

- [ ] **C1 resolved:** Contracts either (a) have stub definitions in AOM, OR (b) are removed from Phase 1 scope
- [ ] **C2 resolved:** Project Standard templates rewritten to match Final Recommendation (README.md single entry, 4-folder KB)
- [ ] **C3 resolved:** Arsenal V3 updated to include Project Standard as first-class component
- [ ] **M1 resolved:** NX consolidation strategy decided and documented
- [ ] **M2 tracked:** AOM path updates added to Phase 0 checklist
- [ ] **M3 tracked:** Project Standard AOM doc added to Phase 0 deliverables

---

## Appendices

### Appendix A: Document Versions Reviewed

| Document | Version/Date | Location |
|----------|-------------|----------|
| Arsenal V3 Webster Review | 2026-02-23 | `Atomizer-AtomasteAI/Development/ARSENAL-V3-WEBSTER-REVIEW.md` |
| Arsenal V3 Final | 2026-02-23 | `Atomizer-AtomasteAI/Development/ARSENAL-V3-FINAL.md` |
| Project Standard Final Recommendation | 2026-02-19 | `P-Atomizer-Project-Standard/05-FINAL-RECOMMENDATION.md` |
| Migration Plan V3.1 | 2026-02-23 (V3.1 amendment) | `Atomizer-AtomasteAI/Development/ATOMIZER-V2-MIGRATION-MASTERPLAN-V3.md` |
| AOM MAP | 2026-02-21 | `P-Atomizer-Operating-Manual/MAP - Atomizer Operating Manual.md` |
| AOM Component Map | 2026-02-22 | `P-Atomizer-Operating-Manual/01-Philosophy/04-Component-Map.md` |
| AOM Tool-Agnostic Architecture | 2026-02-22 | `P-Atomizer-Operating-Manual/01-Philosophy/08-Tool-Agnostic-Architecture.md` |

### Appendix B: Files Counted

- **Arsenal V3:** 1 architecture doc, 6 sprints, 19 agent definitions, 4 MCP servers, 3 architectural layers
- **Migration Plan V3.1:** 8 phases, 163 Python files, 48 AOM docs, 15+ Project Standard templates, 6 verification checklists
- **Project Standard:** 9 top-level items, 14 template files, 4 KB folders, 3 lifecycle phases
- **AOM:** 4 pillars, 48 docs (40 core + 8 auxiliary), 19 agent architecture

### Appendix C: Methodology

1. **Read all 5 source document sets in full** (Arsenal Webster Review, Arsenal Final, Project Standard Final Rec, Migration V3.1, AOM MAP + 2 key architecture docs)
2. **Extract structural definitions** from each (folder paths, component names, module locations)
3. **Cross-reference systematically** across 6 audit dimensions (A-F)
4. **Tag contradictions** by severity (🔴 critical if blocks migration, 🟡 major if causes confusion, 🟢 minor if cosmetic)
5. **Trace gaps** bidirectionally (defined in A but missing from B, AND defined in B but missing from A)
6. **Document every finding** with section references (e.g., "Arsenal V3 §2.2 says X, Migration §3.17 says Y")
7. **Prioritize recommendations** (Critical → Major → Minor)

---

**TASK:** Cross-document coherence audit  
**STATUS:** complete  
**RESULT:** 3 critical contradictions found (contracts undefined, wrong Project Standard templates, Arsenal incomplete). 5 major gaps identified. Migration can proceed after resolving C1-C3.  
**CONFIDENCE:** high  
**NOTES:**
- Arsenal V3 and Tool-Agnostic Architecture are directionally sound but have implementation gaps (contracts are described but not defined, Project Standard not included)
- Migration Plan V3.1 is executable AFTER correcting the Project Standard template error (currently implements rejected spec)
- The core 3-layer architecture (contracts/processors/orchestrator) is perfectly aligned across all documents — this is the strongest finding
- NX consolidation ambiguity is solvable with a CEO decision (not a documentation error, just an unstated choice)
- Recommend 1-2 day hold before Phase 0 start to resolve C1-C3

---

*Audit completed by Auditor (Subagent) on 2026-02-23*  
*All findings traceable to source documents with section references*  
*Severity ratings follow Atomizer audit protocol (🔴🟡🟢)*