# FESA Multi-Agent Work Notes

## Purpose
This file records mistakes, failed attempts, environment traps, and lessons learned so future AI Agents do not repeat them.

Add dated entries. Do not delete another Agent's note unless the user explicitly asks.

## Notes

### 2026-06-05 - HDF5 Not Found In Standard Paths
During planning, standard checks for `HDF5_ROOT`, `HDF5_DIR`, `h5dump`, and obvious Program Files HDF5 folders did not find HDF5. Future implementation should not assume HDF5 is locally installed. Use `HDF5_ROOT` or `HDF5_DIR` and fail CMake configuration with a clear diagnostic if missing.

### 2026-06-08 - HDF5 Installed Under HDF_Group
The local HDF5 install was later confirmed at `C:\Program Files\HDF_Group\HDF5\2.1.1`, and `h5dump.exe -V` reports `2.1.1`. Future CMake work should prefer `HDF5_ROOT=C:\Program Files\HDF_Group\HDF5\2.1.1` or `HDF5_DIR=C:\Program Files\HDF_Group\HDF5\2.1.1\cmake`. Keep the old 2026-06-05 note as historical context for stale sessions, but do not treat HDF5 as currently missing on this machine.

### 2026-06-08 - CMake Installed But Not On Shell PATH
`cmake.exe` exists at `C:\Program Files\CMake\bin\cmake.exe`, but the Codex shell did not resolve bare `cmake`. `scripts/validate_workspace.py` was updated to resolve bare `cmake` and `ctest` validation commands to the known CMake install path when needed. Use `python scripts/validate_workspace.py` as the canonical validation path, or call `C:\Program Files\CMake\bin\cmake.exe` / `ctest.exe` explicitly for manual commands.

### 2026-06-05 - Validation Currently Has No CMake Project
`python scripts/validate_workspace.py` currently exits successfully through the no-op path because there is no root `CMakeLists.txt`. This is expected until the C++ solver project is bootstrapped. Once CMake is introduced, validation must configure, build, and run CTest.

### 2026-06-05 - Reference Solvers Are Not Agent-Run
Agents must not run Abaqus or Nastran. Reference artifacts must come from a human-approved process and be stored under `references/<feature>/<model-id>/`.

### 2026-06-05 - Keep Reaction Recovery Full-System Based
For constrained DOF elimination, reactions must be recovered as `K_full * U_full - F_full`. Do not compare reactions computed only from the reduced system.

### 2026-06-05 - Avoid PowerShell UTF-8 BOM For TOML And SKILL.md
PowerShell `Set-Content -Encoding UTF8` added a UTF-8 BOM to `.codex/agents/*.toml` and `.codex/skills/*/SKILL.md`. That broke `tomllib` with `Invalid statement (at line 1, column 1)` and broke skill frontmatter parsing because files no longer started with `---`. Use BOM-free UTF-8 for mechanical rewrites, for example `[System.Text.UTF8Encoding]::new($false)` with `.NET` `WriteAllText`.

### 2026-06-05 - Mechanical Path Replacement Can Rewrite The New Target File
When replacing old document references with `docs/AGENT_RULES.md`, the new rules file itself was also included in the replacement set and briefly became self-referential. Future broad path rewrites should exclude the newly created target file or inspect it immediately after replacement.