Atomizer/hq/workspaces/auditor/memory/reviews/2026-02-18-project-standard-audit.md

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