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,66 @@
+# Sprint Contract: Math Solver Extraction
+
+## Objective
+Move math primitives, dense test matrix support, sparse pattern data, and linear solver interfaces into `Math` while keeping future MKL integration behind an adapter boundary.
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /phases/1-structure-alignment-refactor/step0-architecture-map.md
+- /phases/1-structure-alignment-refactor/step2.md
+
+## Scope
+- Extract vector/matrix helpers, `DenseMatrix`, sparse pattern structures, `SolveResult`, `LinearSolver`, and the deterministic test solver.
+- Keep the production-facing solver dependency expressed through `LinearSolver`.
+- Preserve int64 sparse index and equation-number boundaries.
+- Keep MKL/PARDISO as a future adapter, not a Phase 1 dependency.
+
+## Allowed Files
+- `include/fesa/fesa.hpp`
+- `include/fesa/Math/`
+- `src/Math/`
+- `include/fesa/Core/`
+- `src/Core/`
+- `tests/`
+- `CMakeLists.txt`
+- `phases/1-structure-alignment-refactor/index.json`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not introduce MKL, TBB, HDF5, or production sparse storage.
+- Do not change Gaussian solver numerical behavior except for mechanical relocation.
+- Do not move MITC4, parser, results, assembly, or analysis logic except for include dependency repair.
+
+## Tests To Write First
+- Add or update include/link tests for the `Math` module.
+- Preserve existing small linear algebra, sparse-pattern, solver-injection, and singular-solver diagnostic tests as characterization tests.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- `Math` does not depend on `IO`, `Results`, `Element`, `Assembly`, or `Analysis`.
+- `LinearSolver` remains an adapter boundary.
+- All ids, equation ids, nonzero counts, and sparse indices remain int64.
+- Solver failure diagnostics still propagate to analysis tests.
+- No external library API leaks into solver core.
+
+## Handoff Requirements
+- Update this step status in `phases/1-structure-alignment-refactor/index.json`.
+- Record moved math/solver files and any remaining math symbols still left in `fesa.hpp`.
+
+## Do Not
+- Do not optimize the solver while moving files.
+- Do not replace deterministic tests with tolerance changes.