docs: plan phase1 structure alignment refactor

2026-05-05 00:19:35 +09:00
parent 7b332df1a8
commit 0aecc8233e
14 changed files with 785 additions and 4 deletions
@@ -0,0 +1,63 @@
+# Sprint Contract: Module Scaffold And Facade
+
+## Objective
+Create the target module directory scaffold and public include facade policy so later steps can move code incrementally while preserving existing tests and user includes.
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /phases/1-structure-alignment-refactor/step0-architecture-map.md
+
+## Scope
+- Add the documented module directories under `include/fesa/` and `src/` as needed, including `Analysis`, `Assembly`, `Boundary`, `Core`, `Element`, `IO`, `Load`, `Math`, `Material`, `Property`, `Results`, and `Util`.
+- Update `CMakeLists.txt` so future `.cpp` files under the module directories are compiled by `fesa_core`.
+- Keep `include/fesa/fesa.hpp` as the stable umbrella header for current tests and clients.
+- Add minimal module header smoke coverage proving selected module headers and `fesa/fesa.hpp` can be included together.
+
+## Allowed Files
+- `CMakeLists.txt`
+- `include/fesa/`
+- `src/`
+- `tests/`
+- `phases/1-structure-alignment-refactor/index.json`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not move large implementations yet.
+- Do not change class names, namespaces, DOF order, result labels, parser behavior, or solver outputs.
+- Do not add MKL, TBB, or HDF5 dependencies.
+- Do not replace the umbrella header with module-only includes.
+
+## Tests To Write First
+- Add or update a compile/include smoke test that includes the new module headers and `fesa/fesa.hpp` together.
+- The test should fail before the scaffold exists and pass after the scaffold is added.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Module directory names align with `docs/ARCHITECTURE.md`.
+- `fesa_core` builds with the scaffold on Windows/MSVC.
+- Existing tests still include `fesa/fesa.hpp` successfully.
+- New module headers do not expose external MKL, TBB, or HDF5 APIs.
+- No solver behavior changes are mixed into the scaffold.
+
+## Handoff Requirements
+- Update this step status in `phases/1-structure-alignment-refactor/index.json`.
+- Record validation output and any CMake/source-list decisions in `PROGRESS.md`.
+- Leave detailed code movement to later steps.
+
+## Do Not
+- Do not introduce broad formatting churn in `fesa.hpp`.
+- Do not change public API semantics while creating empty or thin module boundaries.