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,77 @@
+# Sprint Contract: Core Domain DOF Extraction
+
+## Objective
+Move core types, diagnostics, domain data, validation, `AnalysisModel`, `DofManager`, and Phase 1 boundary/load/property model ownership out of the monolithic header into the documented `Core`, `Util`, `Boundary`, `Load`, and `Property` module boundaries.
+
+## 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/step1.md
+
+## Scope
+- Extract numeric aliases, diagnostics, DOF enum/mapping, domain entities, domain validation helpers, `AnalysisModel`, and `DofManager`.
+- Extract Phase 1 `BoundaryCondition`, `NodalLoad`, and `ShellSection` ownership into `Boundary`, `Load`, and `Property` module headers or implementation files while keeping `Domain` as the aggregate input model.
+- Keep `Node` and `Element` free of equation ids.
+- Keep `Domain` as input-model ownership and treat it as immutable after parsing.
+- Preserve existing symbol names and the `fesa` namespace unless a compiler-visible conflict requires a narrow adjustment.
+
+## Allowed Files
+- `include/fesa/fesa.hpp`
+- `include/fesa/Core/`
+- `include/fesa/Util/`
+- `include/fesa/Boundary/`
+- `include/fesa/Load/`
+- `include/fesa/Property/`
+- `src/Core/`
+- `src/Util/`
+- `src/Boundary/`
+- `src/Load/`
+- `src/Property/`
+- `tests/`
+- `CMakeLists.txt`
+- `phases/1-structure-alignment-refactor/index.json`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not move parser, MITC4 element, assembly, analysis, solver, material-law, or result writer code in this step except for include dependency repair.
+- Do not change DOF order or Abaqus DOF mapping.
+- Do not change reaction recovery formulas.
+- Do not add runtime polymorphic interfaces that are not needed for this extraction.
+
+## Tests To Write First
+- Add or update focused tests proving module includes expose `DofManager`, `Domain`, diagnostics, DOF mapping, Phase 1 boundary/load/property model types, and the umbrella header.
+- Preserve existing DofManager and domain validation behavioral tests as characterization tests.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Core ownership matches `docs/ARCHITECTURE.md`.
+- Boundary, Load, and Property Phase 1 model types are no longer hidden only in `fesa.hpp`.
+- `DofManager` still owns constrained/free mapping, equation numbering, sparse connectivity inputs, and full-vector reconstruction.
+- Numeric aliases remain `double` and signed int64.
+- `Node` and `Element` do not store global equation ids.
+- Existing parser, analysis, and reference tests still pass.
+
+## Handoff Requirements
+- Update this step status in `phases/1-structure-alignment-refactor/index.json`.
+- Record moved files and any remaining Core symbols still left in `fesa.hpp`.
+- Update `PLAN.md` if the extraction reveals a dependency cycle that requires a later contract change.
+
+## Do Not
+- Do not weaken tests to accommodate include-order problems.
+- Do not let `Core` depend on `IO`, `Element`, `Assembly`, `Analysis`, or `Results`.
+- Do not create circular dependencies between `Core`, `Boundary`, `Load`, and `Property`.