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,64 @@
+# Sprint Contract: Architecture Drift Audit
+
+## Objective
+Create a precise migration map from the current monolithic `include/fesa/fesa.hpp` implementation to the module ownership model documented in `docs/ARCHITECTURE.md`, without changing production solver behavior.
+
+## 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-linear-static-mitc4-rebaseline/step15-evaluator-report.md
+
+## Scope
+- Audit current symbols, functions, classes, and tests that are concentrated in `include/fesa/fesa.hpp` and `tests/test_main.cpp`.
+- Assign every Phase 1 production symbol to one target module from `docs/ARCHITECTURE.md`: `Analysis`, `Assembly`, `Boundary`, `Core`, `Element`, `IO`, `Load`, `Math`, `Material`, `Property`, `Results`, or `Util`.
+- Produce a handoff artifact at `phases/1-structure-alignment-refactor/step0-architecture-map.md`.
+- Identify public API compatibility rules for keeping `include/fesa/fesa.hpp` as an umbrella facade during the refactor.
+
+## Allowed Files
+- `phases/1-structure-alignment-refactor/step0-architecture-map.md`
+- `phases/1-structure-alignment-refactor/index.json`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not move C++ code in this step.
+- Do not change `CMakeLists.txt`.
+- Do not change parser support, MITC4 formulas, solver behavior, reference tolerances, or numerical conventions.
+- Do not create new architecture decisions unless the audit proves `docs/ARCHITECTURE.md` itself must change.
+
+## Tests To Write First
+- None. This is an audit and handoff step.
+- Before writing the audit artifact, run `python scripts/validate_workspace.py` to capture the pre-refactor baseline.
+
+## Reference Artifacts
+- `references/quad_02_phase1.inp`
+- `references/quad_02_displacements.csv`
+
+These artifacts are baseline evidence only. Do not edit them.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- The map assigns all major Phase 1 production areas from `fesa.hpp` to target modules.
+- The map calls out dependency direction and extraction order.
+- The map preserves `include/fesa/fesa.hpp` as an umbrella facade unless an ADR changes the public API.
+- The map explicitly records that this phase is behavior-preserving.
+- PLAN/PROGRESS reflect this architecture debt as active work.
+
+## Handoff Requirements
+- Update this step status in `phases/1-structure-alignment-refactor/index.json`.
+- Record changed files, validation output, and any blockers in `PROGRESS.md`.
+- Keep the next refactor step in `PLAN.md`.
+
+## Do Not
+- Do not treat this audit as approval to change formulas or parser scope.
+- Do not use this phase to close R-010 or R-013.