# AUDIT REPORT: Atomizer Project Standard Specification v1.0

**Auditor:** 🔍 Auditor Agent  
**Date:** 2026-02-18  
**Document Under Review:** `/home/papa/obsidian-vault/2-Projects/P-Atomizer-Project-Standard/00-SPECIFICATION.md`  
**Audit Level:** Profound (foundational infrastructure)  
**Confidence Level:** HIGH — all primary sources reviewed, codebase cross-referenced

---

## Executive Summary

The specification is **strong foundational work** — well-researched, clearly structured, and largely aligned with Antoine's vision. It successfully synthesizes the KB methodology, existing project patterns, and industry standards into a coherent system. However, there are several gaps between what Antoine asked for and what was delivered, some compatibility issues with the actual Atomizer codebase, and a few structural inconsistencies that need resolution before this becomes the production standard.

**Overall Rating: 7.5/10 — GOOD with REQUIRED FIXES before adoption**

---

## Criterion-by-Criterion Assessment

---

### 1. COMPLETENESS — Does the spec cover everything Antoine asked for?

**Rating: CONCERN ⚠️**

Cross-referencing the Project Directive and the detailed standardization ideas document against the spec:

#### ✅ COVERED
| Requirement (from Directive) | Spec Coverage |
|------------------------------|---------------|
| Self-contained project folder | P1 principle, thoroughly addressed |
| LLM-native documentation | P2, AGENT.md, frontmatter |
| Expandable structure | P3, study numbering, KB branches |
| Compatible with Atomizer files | P4, file mappings in AGENT.md |
| Co-evolving template | P5, §13 versioning |
| Practical for solo consultant | P6 principle |
| Project context/mandate | `00-context/` folder |
| Model baseline | `01-models/` folder |
| KB (design, analysis, manufacturing) | `02-kb/` full structure |
| Optimization setup | `03-studies/` with atomizer_spec.json |
| Study management | §6 Study Lifecycle |
| Results & reporting | §8 Report Generation |
| Project-specific tools | `05-tools/` |
| Introspection | `02-kb/introspection/` |
| Status & navigation | `STATUS.md`, `PROJECT.md` |
| LLM bootstrapping | `AGENT.md` |
| Study evolution narrative | `03-studies/README.md` |
| Decision rationale capture | `DECISIONS.md` with IBIS pattern |
| Fictive validation project | §10 ThermoShield Bracket |
| Naming conventions | §11 |
| Migration strategy | §12 |

#### ❌ MISSING OR INADEQUATE
| Requirement | Issue |
|-------------|-------|
| **JSON schemas for all configs** | Directive §7 quality criteria: "All config files have JSON schemas for validation." Only `project.json` gets a schema sketch. No JSON schema for `atomizer_spec.json` placement rules, no `template-version.json` schema, no `hooks.json` schema. |
| **Report generation scripts** | Directive §5.7 asks for auto-generation protocol AND scripts. Spec describes the protocol but never delivers scripts or even pseudocode. |
| **Introspection protocol scripts** | Directive §5.5 asks for "Python scripts that open NX models and extract KB content." The spec describes what data to extract (§7.2) but provides no scripts, no code, no pseudocode. |
| **Template instantiation CLI** | Directive §5.8 describes `atomizer project create`. The spec mentions it (§9.1) but defers it to "future." No interim solution (e.g., a shell script or manual checklist). |
| **Dashboard integration** | Directive explicitly mentions "What data feeds into the Atomizer dashboard." The spec's §13.2 mentions "Dashboard integration" as a future trigger but provides ZERO specification for it. |
| **Detailed document example content** | Directive §5.2: "Fill with realistic example content based on the M1 mirror project (realistic, not lorem ipsum)." The spec uses a fictive ThermoShield project instead of M1 Mirror for examples. While the fictive project is good, the directive specifically asked for M1 Mirror-based content. |
| **Cross-study comparison reports** | Directive §5.7 asks for "Project summary reports — Cross-study comparison." The spec mentions "Campaign Summary" in the report types table but provides no template or structure for it. |

#### Severity Assessment
- JSON schemas: 🟡 MAJOR — needed for machine validation, was explicit requirement
- Scripts: 🟡 MAJOR — spec was asked to deliver scripts, not just describe them  
- Dashboard: 🟢 MINOR — legitimately deferred, but should say so explicitly
- M1 Mirror examples: 🟢 MINOR — the fictive project actually works better as a clean example

---

### 2. GAPS — What scenarios aren't covered?

**Rating: CONCERN ⚠️**

#### 🔴 CRITICAL GAPS

**Gap G1: Multi-solver projects**  
The spec is entirely NX Nastran-centric. No accommodation for:
- Projects using multiple solvers (e.g., Nastran for static + Abaqus for nonlinear contact)
- Projects using non-FEA solvers (CFD, thermal, electromagnetic)
- The `02-kb/analysis/solver/nastran-settings.md` template hardcodes Nastran

**Recommendation:** Generalize to `solver-config.md` or `{solver-name}-settings.md`. Add a note in the spec about multi-solver handling.

**Gap G2: Assembly FEM projects**  
The spec's `01-models/` assumes a single-part model flow (one .prt, one .fem, one .sim). Real Assembly FEM projects have:
- Multiple .prt files (component parts + assembly)
- Multiple .fem files (component FEMs + assembly FEM)
- Assembly-level boundary conditions that differ from part-level
- The M1 Mirror is literally `ASSY_M1_assyfem1_sim1.sim` — an assembly model

**Recommendation:** Add guidance for assembly model organization under `01-models/`. Perhaps `cad/assembly/`, `cad/components/`, `fem/assembly/`, `fem/components/`.

**Gap G3: `2_iterations/` folder completely absent from spec**  
The actual Atomizer engine uses `1_setup/`, `2_iterations/`, `3_results/`, `3_insights/`. The spec's study structure shows `1_setup/` and `3_results/` but **completely omits `2_iterations/`** — the folder where individual FEA iteration outputs go. This is where the bulk of data lives (potentially GBs of .op2, .f06 files).

**Recommendation:** Add `2_iterations/` to the study structure. Even if it's auto-managed by the engine, it needs to be documented. Also add `3_insights/` which is the actual name used by the engine.

#### 🟡 MAJOR GAPS

**Gap G4: Version control of models**  
No guidance on how model versions are tracked. `01-models/README.md` mentions "version log" but there's no mechanism for:
- Tracking which model version each study used
- Rolling back to previous model versions
- Handling model changes mid-campaign (what happens to running studies?)

**Gap G5: Collaborative projects**  
The spec assumes solo operation. No mention of:
- Multiple engineers working on the same project
- External collaborators who need read access
- Git integration or version control strategy

**Gap G6: Large binary file management**  
NX model files (.prt), FEM files (.fem), and result files (.op2) are large binaries. No guidance on:
- Git LFS strategy
- What goes in version control vs. what's generated/temporary
- Archiving strategy for completed studies with GBs of iteration data

**Gap G7: `optimization_config.json` backward compatibility**  
The spec only mentions `atomizer_spec.json` (v2.0). But the actual codebase still supports `optimization_config.json` (v1.0) — gate.py checks both locations. Existing studies use the old format. Migration path between config formats isn't addressed.

#### 🟢 MINOR GAPS

**Gap G8:** No guidance on `.gitignore` patterns for the project folder  
**Gap G9:** No mention of environment setup (conda env, Python deps)  
**Gap G10:** No guidance on how images/ folder scales (hundreds of study plots over 20 studies)  
**Gap G11:** The `playbooks/` folder is unnumbered — inconsistent with the numbering philosophy

---

### 3. CONSISTENCY — Internal consistency check

**Rating: CONCERN ⚠️**

#### Naming Convention Contradictions

**Issue C1: KB component files — PascalCase vs kebab-case**  
§11.1 says KB component files use `PascalCase.md` → example: `Bracket-Body.md`  
But `Bracket-Body.md` is NOT PascalCase — it's PascalCase-with-hyphens. True PascalCase would be `BracketBody.md`. The KB System source uses `PascalCase.md` for components and `CAPS-WITH-DASHES.md` for materials.

The spec's example shows `Ti-6Al-4V.md` under both `02-kb/design/materials/` AND references material knowledge — but §11.1 says materials are `PascalCase.md`. Ti-6Al-4V is neither PascalCase nor any consistent convention; it's the material's actual name with hyphens.

**Recommendation:** Clarify: component files are `Title-Case-Hyphenated.md` (which is what they actually are), material files use the material's standard designation. Drop the misleading "PascalCase" label.

**Issue C2: Analysis KB files are lowercase-kebab, but component KB files are "PascalCase"**  
This means `02-kb/design/components/Bracket-Body.md` and `02-kb/analysis/boundary-conditions/mounting-constraints.md` use different conventions under the SAME `02-kb/` root. The split is Design=PascalCase, Analysis=kebab-case. While there may be a rationale (components are proper nouns, analysis entries are descriptive), this isn't explained.

**Issue C3: Playbooks are UPPERCASE.md but inside an unnumbered folder**  
Top-level docs are UPPERCASE.md (PROJECT.md, AGENT.md). Playbooks inside `playbooks/` are also UPPERCASE.md (FIRST_RUN.md). But `playbooks/` itself has no number prefix while all other content folders do (00-06). This is inconsistent with the "numbered for reading order" philosophy.

**Issue C4: `images/` vs `06-data/` placement**  
`images/` is unnumbered at root level. `06-data/` is numbered. Both contain project assets. Why is `images/` exempt from numbering? The spec doesn't explain this.

#### Cross-Reference Issues

**Issue C5: Materials appear in TWO locations**  
Materials exist in both `02-kb/design/materials/` AND `02-kb/analysis/materials/` (mentioned in §4.1 table row for "BC documentation + rationale" which incorrectly labels an analysis/materials entry). The KB System source puts materials under `Design/` only, with cross-references from Analysis. The spec duplicates the location, creating ambiguity about which is the source of truth.

Wait — re-reading: `02-kb/analysis/` has no explicit `materials/` subfolder in the canonical structure (§2.1). But §4.1's specification table mentions `02-kb/analysis/materials/*.md`. This is a **direct contradiction** between the folder structure and the document spec table.

**Issue C6: Study folder internal naming**  
The spec shows `1_setup/` and `3_results/` (with number prefixes) inside studies. But the actual codebase also uses `2_iterations/` and `3_insights/`. The spec skips `2_iterations/` entirely and doesn't mention `3_insights/`. If the numbering scheme is meant to match the engine's convention, it must be complete.

#### Minor Inconsistencies

**Issue C7:** §2.1 shows `baseline/results/` under `01-models/` but §9.2 Step 3 says "Copy baseline solver output to `01-models/baseline/results/`" — consistent, but the path is redundant (`baseline/results/` under `01-models/baseline/`).

**Issue C8:** AGENT.md template shows `atomizer_protocols: "POS v1.1"` in frontmatter. "POS" is never defined in the spec. Presumably "Protocol Operating System" but this should be explicit.

---

### 4. PRACTICALITY — Would this work for a solo consultant?

**Rating: PASS ✅ (with notes)**

The structure is well-calibrated for a solo consultant:

**Strengths:**
- The 7-folder + root docs pattern is manageable
- KB population strategy correctly identifies auto vs. manual vs. semi-auto
- The study lifecycle stages are realistic and not over-bureaucratic
- Playbooks solve real problems (the Hydrotech project already has them organically)
- The AGENT.md / PROJECT.md split is pragmatic

**Concerns:**
- **Overhead for small projects:** A 1-study "quick check" project would still require populating 7 top-level folders + 5 root docs + .atomizer/. This is heavy for a 2-day job. The spec should define a **minimal viable project** profile (maybe just PROJECT.md + 00-context/ + 01-models/ + 03-studies/).
- **KB population effort:** §7.3 lists 14 user-input questions. For a time-pressed consultant, this is a lot. Should prioritize: which questions are MANDATORY for optimization to work vs. NICE-TO-HAVE for documentation quality?
- **Template creation still manual:** Until the CLI exists, creating a new project from scratch means copying ~30+ folders and files. A simple `init.sh` script should be provided as a stopgap.

**Recommendation:** Add a "Minimal Project" profile (§2.3) that shows the absolute minimum files needed to run an optimization. Everything else is progressive enhancement.

---

### 5. ATOMIZER COMPATIBILITY — Does it match the engine?

**Rating: CONCERN ⚠️**

#### 🔴 CRITICAL

**Compat-1: Study folder path mismatch**  
The Atomizer CLI (`optimization_engine/cli/main.py`) uses `find_project_root()` which looks for a `CLAUDE.md` file to identify the repo root, then expects studies at `{root}/studies/{study_name}`. The spec proposes `{project}/03-studies/{NN}_{slug}/`.

This means:
- `find_project_root()` won't find a project's studies because it looks for `CLAUDE.md` at repo root, not in project folders
- The engine expects `studies/` not `03-studies/`
- Study names in the engine don't have `{NN}_` prefixes — they're bare slugs

**Impact:** The engine CANNOT find studies in the new structure without code changes. The spec acknowledges this in Decision D3 ("needs a `--project-root` flag") but doesn't specify the code changes needed or provide a compatibility shim.

**Recommendation:** Either (a) specify the exact engine code changes as a dependency, or (b) use symlinks/config for backward compat, or (c) keep `studies/` without number prefix and add numbers via the study folder name only.

**Compat-2: `2_iterations/` missing from spec**  
Already noted in Gaps. The engine creates and reads from `2_iterations/`. The spec's study structure omits it entirely. Any agent following the spec would not understand where iteration data lives.

**Compat-3: `3_insights/` missing from spec**  
The engine's insights system writes to `3_insights/` (see `base.py:172`). The spec doesn't mention this folder.

**Compat-4: `atomizer_spec.json` placement ambiguity**  
The engine checks TWO locations: `{study}/atomizer_spec.json` AND `{study}/1_setup/atomizer_spec.json` (gate.py:180-181). The spec puts it at `{study}/atomizer_spec.json` (study root). This works with the engine's fallback, but is inconsistent with the M1 Mirror V9 which has it at root alongside `1_setup/optimization_config.json` inside setup. The spec should explicitly state that study root is canonical and `1_setup/` is legacy.

#### 🟡 MAJOR

**Compat-5: `optimization_config.json` not mentioned**  
Many existing studies use the v1.0 config format. The spec only references `atomizer_spec.json`. The migration path from old config to new config isn't documented.

**Compat-6: `optimization_summary.json` not in spec**  
The actual study output includes `3_results/optimization_summary.json` (seen in M1 Mirror V9). The spec doesn't mention this file.

---

### 6. KB ARCHITECTURE — Does it follow Antoine's KB System?

**Rating: PASS ✅ (with deviations noted)**

The spec correctly adopts:
- ✅ Unified root with Design and Analysis branches
- ✅ `_index.md` at each level
- ✅ One-file-per-entity pattern
- ✅ Session captures in `dev/gen-NNN.md`
- ✅ Cross-reference between Design and Analysis
- ✅ Component file template with Specifications table + Confidence column

**Deviations from KB System source:**

| KB System Source | Spec | Assessment |
|-----------------|------|------------|
| `KB/` root | `02-kb/` root | ✅ Acceptable — numbered prefix adds reading order |
| `Design/` (capital D) | `design/` (lowercase) | ⚠️ KB source uses uppercase. Spec uses lowercase. Minor but pick one. |
| `Analysis/` (capital A) | `analysis/` (lowercase) | Same as above |
| Materials ONLY in `Design/materials/` | Materials referenced in both design and analysis | ⚠️ Potential confusion — source is clear: materials live in Design, analysis cross-refs |
| `Analysis/results/` subfolder | Results live in `03-studies/{study}/3_results/` | ✅ Better — results belong with studies, not in KB |
| `Analysis/optimization/` subfolder | Optimization is `03-studies/` | ✅ Better — same reason |
| `functions/` subfolder in Design | **Missing** from spec | ⚠️ KB source has `Design/functions/` for functional requirements. Spec drops it. May be intentional (functional reqs go in `00-context/requirements.md`?) but not explained. |
| `Design/inputs/` subfolder | **Missing** from spec | ⚠️ KB source has `Design/inputs/` for manual inputs (photos, etc.). Spec drops it. Content may go to `06-data/inputs/` or `images/`. Not explained. |
| Image structure: `screenshot-sessions/` | `screenshots/gen-NNN/` | ✅ Equivalent, slightly cleaner |

**Recommendation:** Justify the deviations explicitly. The `functions/` and `inputs/` omissions should be called out as intentional decisions with rationale.

---

### 7. LLM-NATIVE — Can an AI bootstrap in 60 seconds?

**Rating: PASS ✅**

This is one of the spec's strongest areas.

**Strengths:**
- PROJECT.md is well-designed: Quick Facts table → Overview → Key Results → Navigation → Team. An LLM reads this in 15 seconds and knows the project.
- AGENT.md has decision trees for common operations — this is excellent.
- File Mappings table in AGENT.md maps Atomizer framework concepts to project locations — crucial for operational efficiency.
- Frontmatter metadata on all key documents enables structured parsing.
- STATUS.md as a separate file is smart — LLMs can check project state without re-reading the full PROJECT.md.

**Concerns:**
- **AGENT.md info density:** The template shows 4 decision trees (run study, analyze results, answer question, and implicit "generate report"). For a complex project, this could grow to 10+ decision trees and become unwieldy. No guidance on when to split AGENT.md or use linked playbooks instead.
- **Bootstrap test:** The spec claims "<60 seconds" bootstrapping. With PROJECT.md (~2KB) + AGENT.md (~3KB), that's ~5KB of reading. Claude can process this in ~5 seconds. The real question is whether those 5KB contain ENOUGH to be operational. Currently yes for basic operations, but missing: what solver solution sequence to use, what extraction method to apply, what units system the project uses. These are in the KB but not in the bootstrap docs.
- **Missing: "What NOT to do" section** in AGENT.md — known gotchas, anti-patterns, things that break the model. This exists informally in the M1 Mirror (e.g., "don't use `abs(RMS_target - RMS_ref)` — always use `extract_relative()`").

**Recommendation:** Add a "⚠️ Known Pitfalls" section to the AGENT.md template. These are the highest-value items for LLM bootstrapping — they prevent costly mistakes.

---

### 8. MIGRATION FEASIBILITY — Is migration realistic?

**Rating: PASS ✅ (with caveats)**

**Hydrotech Beam Migration:**
The mapping table in §12.1 is clear and actionable. The Hydrotech project already has `kb/`, `models/`, `studies/`, `playbooks/`, `DECISIONS.md` — it's 70% there. Migration is mostly renaming + restructuring.

**Concern:** Hydrotech has `dashboard/` — not mentioned in the spec. Where does dashboard config go? `.atomizer/`? `05-tools/`?

**M1 Mirror Migration:**
§12.2 outlines 5 steps. This is realistic but underestimates the effort:

- **Step 3 ("Number studies chronologically")** is a massive undertaking. M1 Mirror has 25+ study folders with non-sequential naming (V6-V15, flat_back_V3-V10, turbo_V1-V2). Establishing a chronological order requires reading every study's creation date. Some studies ran in parallel (adaptive campaign + cost reduction campaign simultaneously).

**Critical Question:** The spec assumes sequential numbering (01, 02, ...). But M1 Mirror had PARALLEL campaigns. The spec's numbering scheme (`{NN}_{slug}`) can't express "Studies 05-08 ran simultaneously as Phase 2" without the phase grouping mechanism (mentioned as "optional topic subdirectories" in Decision D5 but never fully specified).

**Recommendation:** Flesh out the optional topic grouping. Show how M1 Mirror's parallel campaigns would map: e.g., `03-studies/phase1-adaptive/01_v11_gnn_turbo/`, `03-studies/phase2-cost-reduction/01_tpe_baseline/`.

---

### 9. INDUSTRY ALIGNMENT — NASA-STD-7009 and ASME V&V 10 claims

**Rating: CONCERN ⚠️**

The spec claims alignment in Appendix A. Let me verify:

**NASA-STD-7009:**

| Claim | Accuracy |
|-------|----------|
| "Document all assumptions" → DECISIONS.md | ⚠️ PARTIAL — NASA-STD-7009 requires a formal **Assumptions Register** with impact assessment and sensitivity to each assumption. DECISIONS.md captures rationale but doesn't have "impact if assumption is wrong" or "sensitivity" fields. |
| "Model verification" → validation/ | ⚠️ PARTIAL — NASA-STD-7009 distinguishes verification (code correctness — does the code solve the equations right?) from validation (does it match reality?). The spec's `validation/` folder conflates both. |
| "Uncertainty quantification" → parameter-sensitivity.md | ⚠️ PARTIAL — Sensitivity analysis ≠ UQ. NASA-STD-7009 UQ requires characterizing input uncertainties, propagating them, and quantifying output uncertainty bounds. The spec's sensitivity analysis only covers "which parameters matter most," not formal UQ. |
| "Configuration management" → README.md + CHANGELOG | ✅ Adequate for a solo consultancy |
| "Reproducibility" → atomizer_spec.json + run_optimization.py | ✅ Good |

**ASME V&V 10:**

| Claim | Accuracy |
|-------|----------|
| "Conceptual model documentation" → analysis/models/ | ✅ Adequate |
| "Computational model documentation" → atomizer_spec.json + solver/ | ✅ Adequate |
| "Solution verification (mesh convergence)" → analysis/mesh/ | ⚠️ PARTIAL — The folder exists but the spec doesn't require mesh convergence studies. It just says "mesh strategy + decisions." ASME V&V 10 is explicit about systematic mesh refinement studies. |
| "Validation experiments" → analysis/validation/ | ✅ Adequate |
| "Prediction with uncertainty" → Study reports + sensitivity | ⚠️ Same UQ gap as above |

**Assessment:** The claims are **aspirational rather than rigorous**. The structure provides hooks for NASA/ASME compliance but doesn't enforce it. This is honest for a solo consultancy — full compliance would require formal UQ and V&V processes beyond the scope. But the spec should tone down the language from "alignment" to "provides infrastructure compatible with" these standards.

**Recommendation:** Change Appendix A title from "Comparison to Industry Standards" to "Industry Standards Compatibility" and add a note: "Full compliance requires formal V&V and UQ processes beyond the scope of this template."

---

### 10. SCALABILITY — 1-study to 20-study projects

**Rating: PASS ✅**

**1-Study Project:**
Works fine. Most folders will be near-empty, which is harmless. The structure is create-and-forget for unused folders.

**20-Study Campaign:**
The M1 Mirror has 25+ studies and the structure handles it through:
- Sequential numbering (prevents sorting chaos)
- Study evolution narrative (provides coherent story)
- Optional topic grouping (§ Decision D5)
- KB introspection that accumulates across studies

**Concern for 20+ studies:**
- `images/studies/` would have 20+ subfolders with potentially hundreds of plots. No archiving or cleanup guidance.
- The study evolution narrative in `03-studies/README.md` would become very long. No guidance on when to split into phase summaries.
- KB introspection files (`parameter-sensitivity.md`, `design-space.md`) would become enormous if truly append-only across 20 studies. Need a consolidation/archiving mechanism.

**Recommendation:** Add guidance for large campaigns: when to consolidate KB introspection, when to archive completed phase data, how to keep the study README manageable.

---

## Line-by-Line Issues

| Location | Issue | Severity |
|----------|-------|----------|
| §2.1, study folder | Missing `2_iterations/` and `3_insights/` | 🔴 CRITICAL |
| §2.1, `02-kb/analysis/` | No `materials/` subfolder in tree, but §4.1 table references it | 🟡 MAJOR |
| §11.1, "PascalCase" for components | `Bracket-Body.md` is not PascalCase, it's hyphenated | 🟡 MAJOR |
| §3.2, AGENT.md frontmatter | `atomizer_protocols: "POS v1.1"` — POS undefined | 🟢 MINOR |
| §2.1, `playbooks/` | Unnumbered folder amidst numbered structure | 🟢 MINOR |
| §2.1, `images/` | Unnumbered folder amidst numbered structure | 🟢 MINOR |
| §4.1, spec table | References `02-kb/analysis/materials/*.md` which doesn't exist in §2.1 | 🟡 MAJOR |
| §5.2, KB branch table | Analysis branch lists `models/`, `mesh/`, etc. but no `materials/` | Confirms §2.1 omission |
| §6.1, lifecycle diagram | Shows `OP_01`, `OP_02`, `OP_03`, `OP_04` without defining them | 🟢 MINOR (they're Atomizer protocols) |
| §9.3, project.json | `"$schema": "https://atomizer.io/schemas/project_v1.json"` — this URL doesn't exist | 🟢 MINOR (aspirational) |
| §10, ThermoShield | Shows `Ti-6Al-4V.md` under `design/materials/` which is correct per KB source | Confirms the `analysis/materials/` in §4.1 is the error |
| §12.2, M1 Mirror migration | Says "Number studies chronologically" — doesn't address parallel campaigns | 🟡 MAJOR |
| Appendix A | Claims "alignment" with NASA/ASME — overstated | 🟡 MAJOR |
| Appendix B | OpenMDAO/Dakota comparison is surface-level but adequate for positioning | 🟢 OK |

---

## Prioritized Recommendations

### 🔴 CRITICAL (Must fix before adoption)

1. **Add `2_iterations/` and `3_insights/` to study folder structure** — These are real folders the engine creates and depends on. Omitting them breaks the spec's own P4 principle (Atomizer-Compatible).

2. **Resolve the `studies/` vs `03-studies/` engine compatibility issue** — Either specify the code changes needed, or keep `studies/` as the folder name and use project-level config for the numbered folder approach. The engine currently can't find studies in `03-studies/`.

3. **Fix `analysis/materials/` contradiction** — Either add `materials/` to the `02-kb/analysis/` folder tree, or remove it from the §4.1 document spec table. Recommended: keep materials in `design/` only (per KB System source) and cross-reference from analysis entries.

### 🟡 IMPORTANT (Should fix before adoption)

4. **Add multi-solver guidance** — At minimum, note that `solver/nastran-settings.md` should be `solver/{solver-name}-settings.md` and show how a multi-solver project would organize this.

5. **Add Assembly FEM guidance** — Show how `01-models/` accommodates assemblies vs. single parts.

6. **Add "Minimal Project" profile** — Define the absolute minimum files for a quick project. Not every project needs all 7 folders populated on day one.

7. **Clarify naming conventions** — Drop "PascalCase" label for component files; call it what it is (Title-Case-Hyphenated or just "the component's proper name"). Explain why Design and Analysis branches use different file naming.

8. **Flesh out parallel campaign support** — Show how the optional topic grouping works for parallel study campaigns (M1 Mirror's adaptive + cost reduction simultaneously).

9. **Tone down industry alignment claims** — Change "alignment" to "compatibility" and add honest caveats about formal UQ and V&V processes.

10. **Add `optimization_config.json` backward compatibility note** — Acknowledge the v1.0 format exists and describe the migration path.

11. **Document `optimization_summary.json`** — It exists in real studies, should be in the spec.

12. **Justify KB System deviations** — Explain why `functions/` and `inputs/` from the KB source were dropped, and why Design/Analysis use lowercase instead of uppercase.

### 🟢 NICE-TO-HAVE (Polish items)

13. Add "⚠️ Known Pitfalls" section to AGENT.md template
14. Add `.gitignore` template for project folders
15. Add guidance for large campaign management (KB consolidation, image archiving)
16. Number or explicitly justify unnumbered folders (`images/`, `playbooks/`)
17. Define "POS" acronym in AGENT.md template
18. Add a simple `init.sh` script as stopgap until CLI exists
19. Add JSON schemas for `template-version.json` and `hooks.json`
20. Add environment setup guidance (conda env name, Python version)

---

## Overall Assessment

| Dimension | Rating |
|-----------|--------|
| **Vision & Design** | ⭐⭐⭐⭐⭐ Excellent — the principles, decisions, and overall architecture are sound |
| **Completeness** | ⭐⭐⭐⭐ Good — covers 85% of requirements, key gaps identified |
| **Accuracy** | ⭐⭐⭐ Adequate — engine compatibility issues and naming inconsistencies need fixing |
| **Practicality** | ⭐⭐⭐⭐ Good — well-calibrated for solo use, needs minimal project profile |
| **Readability** | ⭐⭐⭐⭐⭐ Excellent — well-structured, clear rationale for decisions, good examples |
| **Ready for Production** | ⭐⭐⭐ Not yet — 3 critical fixes needed, then ready for pilot |

**Confidence in this audit: 90%** — All primary sources were read in full. Codebase was cross-referenced. The only uncertainty is whether there are additional engine entry points that further constrain the study folder layout.

**Bottom line:** Fix the 3 critical issues (study subfolder completeness, engine path compatibility, materials contradiction), address the important items, then pilot on Hydrotech Beam. The spec is 85% ready — it needs surgery, not a rewrite.

---

*Audit completed 2026-02-18 by Auditor Agent*