From 0aecc8233ec2151424a26a3ba7a09cde473fa635 Mon Sep 17 00:00:00 2001 From: NINI Date: Tue, 5 May 2026 00:19:35 +0900 Subject: [PATCH] docs: plan phase1 structure alignment refactor --- PLAN.md | 27 +++++- PROGRESS.md | 38 ++++++++- .../1-structure-alignment-refactor/index.json | 16 ++++ .../1-structure-alignment-refactor/step0.md | 64 +++++++++++++++ .../1-structure-alignment-refactor/step1.md | 63 ++++++++++++++ .../1-structure-alignment-refactor/step2.md | 77 +++++++++++++++++ .../1-structure-alignment-refactor/step3.md | 66 +++++++++++++++ .../1-structure-alignment-refactor/step4.md | 72 ++++++++++++++++ .../1-structure-alignment-refactor/step5.md | 72 ++++++++++++++++ .../1-structure-alignment-refactor/step6.md | 68 +++++++++++++++ .../1-structure-alignment-refactor/step7.md | 70 ++++++++++++++++ .../1-structure-alignment-refactor/step8.md | 82 +++++++++++++++++++ .../1-structure-alignment-refactor/step9.md | 70 ++++++++++++++++ phases/index.json | 4 + 14 files changed, 785 insertions(+), 4 deletions(-) create mode 100644 phases/1-structure-alignment-refactor/index.json create mode 100644 phases/1-structure-alignment-refactor/step0.md create mode 100644 phases/1-structure-alignment-refactor/step1.md create mode 100644 phases/1-structure-alignment-refactor/step2.md create mode 100644 phases/1-structure-alignment-refactor/step3.md create mode 100644 phases/1-structure-alignment-refactor/step4.md create mode 100644 phases/1-structure-alignment-refactor/step5.md create mode 100644 phases/1-structure-alignment-refactor/step6.md create mode 100644 phases/1-structure-alignment-refactor/step7.md create mode 100644 phases/1-structure-alignment-refactor/step8.md create mode 100644 phases/1-structure-alignment-refactor/step9.md diff --git a/PLAN.md b/PLAN.md index ea0e677..35a9989 100644 --- a/PLAN.md +++ b/PLAN.md @@ -13,7 +13,7 @@ Every new agent session must read this file together with `PROGRESS.md` before p - If an item becomes obsolete, move it to `PROGRESS.md` with a short reason instead of silently deleting it. ## Current Objective -The `phases/1-linear-static-mitc4-rebaseline` execution path is complete through P1R-15. Continue by closing the remaining product-level Phase 1 reference gaps before claiming the full PRD Phase 1 Definition of Done. The old `phases/1-linear-static-mitc4` path is historical and superseded by the paper-based MITC4 formulation reset. +Execute the Phase 1 structure-alignment refactor in `phases/1-structure-alignment-refactor`, starting with P1A-00 architecture drift audit. This phase must align the current monolithic `include/fesa/fesa.hpp` implementation with the module ownership model in `docs/ARCHITECTURE.md` without changing solver behavior. Product-level Phase 1 reference gaps R-010 and R-013 remain open and must not be hidden by the refactor. ## Required Reading For New Agents 1. `AGENTS.md` @@ -30,10 +30,14 @@ The `phases/1-linear-static-mitc4-rebaseline` execution path is complete through 12. `docs/RESULTS_SCHEMA.md` 13. `docs/MITC4_FORMULATION.md` 14. `phases/index.json` -15. `phases/1-linear-static-mitc4-rebaseline/index.json` -16. `phases/1-linear-static-mitc4/index.json` for historical context only +15. `phases/1-structure-alignment-refactor/index.json` +16. `phases/1-linear-static-mitc4-rebaseline/index.json` +17. `phases/1-linear-static-mitc4/index.json` for historical context only ## Phase Files +- Active phase directory: `phases/1-structure-alignment-refactor` +- Execute with: `python scripts/execute.py 1-structure-alignment-refactor` +- Step numbering is zero-based. `step0.md` audits current architecture drift and writes a symbol-to-module migration map; `step1.md` creates module scaffold and umbrella facade policy; `step2.md` extracts Core/Util domain, diagnostics, DofManager ownership, and Phase 1 Boundary/Load/Property model ownership; `step3.md` extracts Math and solver adapter boundaries; `step4.md` extracts the Abaqus parser into IO; `step5.md` extracts Results and reference comparison code; `step6.md` extracts MITC4 geometry/strain helpers; `step7.md` extracts MITC4 material/stiffness helpers; `step8.md` extracts Assembly and Analysis workflow; `step9.md` is the independent architecture evaluator closeout. - Completed phase directory: `phases/1-linear-static-mitc4-rebaseline` - Historical execution command: `python scripts/execute.py 1-linear-static-mitc4-rebaseline` - Step numbering is zero-based. `step0.md` is complete and recorded in `phases/1-linear-static-mitc4-rebaseline/step0-audit.md`; `step1.md` is complete and created the `quad_02_phase1.inp` normalized reference path; `step2.md` is complete and revalidated core harness guardrails; `step3.md` is complete and revalidated the Phase 1 parser/domain subset; `step4.md` is complete and strengthened validation/singular diagnostics; `step5.md` is complete and revalidated the DofManager/reaction foundation; `step6.md` is complete and revalidated the minimum result model plus displacement CSV comparator; `step7.md` is complete and revalidated MITC4 natural coordinates, tying points, center directors, and integration bases; `step8.md` is complete and revalidated degenerated-continuum displacement, direct covariant strain rows, and MITC shear tying rows; `step9.md` is complete and revalidated plane-stress material, convected-to-local transform, and `2 x 2 x 2` material integration scaffolding; `step10.md` is complete and revalidated MITC4 stiffness, internal force, six-DOF transform, and drilling stabilization; `step11.md` is complete and added MITC4 membrane, bending, shear, twist, drilling-sensitivity, and thin-cantilever locking-sensitivity tests; `step12.md` is complete and revalidated full-space assembly, reduced projection, deterministic sparse-pattern scaffold, solver adapter injection, and full-vector internal/reaction force state; `step13.md` is complete and revalidated active AnalysisModel construction plus input-to-AnalysisState-to-U/RF result workflow; `step14.md` is complete and added the first stored Abaqus displacement regression for `quad_02_phase1`; `step15.md` is complete and recorded the independent evaluator closeout in `phases/1-linear-static-mitc4-rebaseline/step15-evaluator-report.md`. @@ -44,9 +48,26 @@ The `phases/1-linear-static-mitc4-rebaseline` execution path is complete through ## Phase 1 Readiness Tasks | ID | Status | Owner | Task | Source | |---|---|---|---|---| +| R-014 | pending | architecture refactor agent | Align Phase 1 production code with `docs/ARCHITECTURE.md` module ownership. Current implementation is concentrated in `include/fesa/fesa.hpp`; execute `phases/1-structure-alignment-refactor` before treating Phase 1 architecture as accepted. | `docs/ARCHITECTURE.md`, `phases/1-structure-alignment-refactor/` | | R-010 | pending | user + verification agent | Add or define reaction-force reference artifacts, preferably `*_reactions.csv`, or decide that Phase 1 `RF` is verified by equilibrium tests until Abaqus RF CSV is available. | `docs/VERIFICATION_PLAN.md`, `docs/RESULTS_SCHEMA.md` | | R-013 | pending | user + verification agent | Add enough additional small Abaqus S4 reference cases for the PRD target of three stored Phase 1 references: one single-element case, one simple multi-element plate/shell case, and one curved shell benchmark. | `docs/PRD.md`, `docs/VERIFICATION_PLAN.md` | +## Phase 1 Structure Alignment Refactor +This phase is an architecture-preserving refactor. It must not change Phase 1 solver behavior, MITC4 formulation, Abaqus parser subset, numerical conventions, result schema, or reference tolerances. + +| ID | Status | Owner | Objective | Depends On | Acceptance Focus | +|---|---|---|---|---|---| +| P1A-00 | pending | planner/evaluator | Audit `fesa.hpp` architecture drift and create a symbol-to-module migration map. | P1R-15 | Complete migration map and validation baseline | +| P1A-01 | pending | generator | Create module directory scaffold, CMake source boundaries, and umbrella facade policy. | P1A-00 | Module include smoke tests and build stability | +| P1A-02 | pending | generator | Extract Core/Util domain, diagnostics, aliases, DOF mapping, `AnalysisModel`, `DofManager`, and Phase 1 Boundary/Load/Property model ownership. | P1A-01 | Core has no dependency on higher layers; Boundary/Load/Property types are no longer hidden in the umbrella header; DOF tests unchanged | +| P1A-03 | pending | generator | Extract Math and solver adapter boundaries. | P1A-02 | Linear solver interface remains adapter-ready; int64 paths unchanged | +| P1A-04 | pending | generator | Extract Abaqus parser into IO. | P1A-02 | Parser subset and unsupported-feature diagnostics unchanged | +| P1A-05 | pending | generator | Extract Results model, writer boundary, CSV loader, and reference comparator. | P1A-02, P1A-04 | `U`/`RF` schema and `quad_02_phase1` regression unchanged | +| P1A-06 | pending | generator | Extract MITC4 geometry, director, strain, and tying helpers into Element. | P1A-03 | Geometry/strain tests and formulation signs unchanged | +| P1A-07 | pending | generator | Extract MITC4 material, integration, stiffness, drilling, and internal-force helpers. | P1A-06 | Patch, drilling, stiffness, and locking-sensitivity tests unchanged | +| P1A-08 | pending | generator | Extract Assembly and Analysis workflow. | P1A-02, P1A-03, P1A-05, P1A-07 | Full-vector RF, solver injection, and end-to-end reference regression unchanged | +| P1A-09 | pending | evaluator | Independently evaluate final architecture alignment. | P1A-08 | `src/` ownership matches `ARCHITECTURE.md`; umbrella header is facade only | + ## Phase 1 Definition Of Done Phase 1 is complete only when FESA can run a documented linear static MITC4 workflow from input to verified results without requiring Abaqus execution. diff --git a/PROGRESS.md b/PROGRESS.md index f4e7c77..2405576 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -13,10 +13,44 @@ Every new agent session must read this file together with `PLAN.md` before plann - Do not remove history unless the user explicitly asks for archival cleanup. ## Current Status -Phase 1 has a completed rebaseline execution path in `phases/1-linear-static-mitc4-rebaseline`. Steps 0 through 15 are complete, and P1R-15 recorded a pass-with-documented-gaps evaluator closeout. `quad_02_phase1.inp` is now the normalized Phase 1-compatible input path for the stored `quad_02` S4 reference pair, while the original `quad_02.inp` remains preserved unsupported provenance. Core numeric aliases, DOF mapping, validation harness, model diagnostic context, the Phase 1 parser/domain subset, validation/singular diagnostics, DofManager/reaction foundation, minimum result model metadata, displacement CSV comparator foundation, MITC4 geometry/director scaffolding, MITC4 displacement/strain/tying row scaffolding, MITC4 material/transform/integration scaffolding, MITC4 stiffness/drilling/internal-force scaffolding, MITC4 patch/locking-sensitivity tests, full-space assembly, reduced projection, sparse-pattern scaffold, solver adapter injection, full-vector internal/reaction force state, active AnalysisModel construction, input-to-AnalysisState-to-U/RF result workflow, and the first stored Abaqus displacement regression have been revalidated. Full PRD Phase 1 completion still depends on the open reference gaps R-010 and R-013. The old `phases/1-linear-static-mitc4` path is historical and superseded after the MITC4 formulation reset. +Phase 1 has a completed rebaseline execution path in `phases/1-linear-static-mitc4-rebaseline`. Steps 0 through 15 are complete, and P1R-15 recorded a pass-with-documented-gaps evaluator closeout. A follow-up architecture refactor phase is now planned in `phases/1-structure-alignment-refactor` because the current production implementation is concentrated in `include/fesa/fesa.hpp` instead of the module directories documented in `docs/ARCHITECTURE.md`. `quad_02_phase1.inp` is the normalized Phase 1-compatible input path for the stored `quad_02` S4 reference pair, while the original `quad_02.inp` remains preserved unsupported provenance. Core numeric aliases, DOF mapping, validation harness, model diagnostic context, the Phase 1 parser/domain subset, validation/singular diagnostics, DofManager/reaction foundation, minimum result model metadata, displacement CSV comparator foundation, MITC4 geometry/director scaffolding, MITC4 displacement/strain/tying row scaffolding, MITC4 material/transform/integration scaffolding, MITC4 stiffness/drilling/internal-force scaffolding, MITC4 patch/locking-sensitivity tests, full-space assembly, reduced projection, sparse-pattern scaffold, solver adapter injection, full-vector internal/reaction force state, active AnalysisModel construction, input-to-AnalysisState-to-U/RF result workflow, and the first stored Abaqus displacement regression have been revalidated. Full PRD Phase 1 completion still depends on the open architecture/reference gaps R-014, R-010, and R-013. The old `phases/1-linear-static-mitc4` path is historical and superseded after the MITC4 formulation reset. ## Completed Work +### 2026-05-05 - Phase 1 structure-alignment refactor phase planned +Author: Codex + +Changed files: +- `phases/index.json` +- `phases/1-structure-alignment-refactor/index.json` +- `phases/1-structure-alignment-refactor/step0.md` +- `phases/1-structure-alignment-refactor/step1.md` +- `phases/1-structure-alignment-refactor/step2.md` +- `phases/1-structure-alignment-refactor/step3.md` +- `phases/1-structure-alignment-refactor/step4.md` +- `phases/1-structure-alignment-refactor/step5.md` +- `phases/1-structure-alignment-refactor/step6.md` +- `phases/1-structure-alignment-refactor/step7.md` +- `phases/1-structure-alignment-refactor/step8.md` +- `phases/1-structure-alignment-refactor/step9.md` +- `PLAN.md` +- `PROGRESS.md` + +Summary: +- Added a dedicated Phase 1 structure-alignment refactor phase to correct the architecture drift where production code is concentrated in `include/fesa/fesa.hpp`. +- Decomposed the refactor into 10 Harness steps: audit, scaffold/facade, Core/Util plus Boundary/Load/Property extraction, Math/Solver extraction, IO parser extraction, Results/reference extraction, MITC4 geometry/strain extraction, MITC4 material/stiffness extraction, Assembly/Analysis extraction, and independent evaluator closeout. +- Updated `PLAN.md` with R-014 and P1A-00 through P1A-09 so new agents can execute the refactor without private context. + +Verification: +- Parsed `phases/index.json` and `phases/1-structure-alignment-refactor/index.json` with PowerShell `ConvertFrom-Json`. +- Verified all 10 structure-alignment step files contain the required sprint contract sections from `docs/HARNESS_ENGINEERING.md`. +- `python scripts/validate_workspace.py` configured CMake, built `fesa_core` and `fesa_tests`, and ran CTest successfully. +- CTest result: 1 test executable passed. + +Follow-up: +- Start with P1A-00 architecture drift audit. +- Keep R-010 and R-013 visible; the structure refactor does not solve missing reaction CSV or the three-reference PRD target. + ### 2026-05-04 - P1R-15 evaluator closeout completed Author: Codex @@ -844,6 +878,7 @@ Verification: - `python scripts/validate_workspace.py` ran, but reported no configured validation commands. ## Known Blockers +- Phase 1 architecture is not yet accepted: production code is concentrated in `include/fesa/fesa.hpp` instead of the `src/` module layout documented in `docs/ARCHITECTURE.md`. - No reaction-force reference artifact exists yet under `references/`. - The PRD target of three stored Phase 1 reference cases is not yet satisfied; only `quad_02_phase1` is an active stored displacement regression. - The current initial `quad_01.inp` reference contains `S4R`, `Part/Assembly/Instance`, `*Density`, and `NLGEOM=YES`, so it is not a Phase 1 parser acceptance case as-is. @@ -854,3 +889,4 @@ Verification: - Future work could accidentally parse the original `quad_02.inp` instead of the normalized `quad_02_phase1.inp` before parser compatibility is explicitly expanded. - Reaction output may be wrong if full-space stiffness/load data is not preserved or reconstructed. - Large-model support may be weakened if any module narrows ids or sparse indices below int64. +- The structure-alignment refactor could accidentally change solver behavior unless each step preserves characterization tests and `quad_02_phase1` regression coverage. diff --git a/phases/1-structure-alignment-refactor/index.json b/phases/1-structure-alignment-refactor/index.json new file mode 100644 index 0000000..953a98d --- /dev/null +++ b/phases/1-structure-alignment-refactor/index.json @@ -0,0 +1,16 @@ +{ + "project": "FESA", + "phase": "1-structure-alignment-refactor", + "steps": [ + { "step": 0, "name": "architecture-drift-audit", "status": "pending" }, + { "step": 1, "name": "module-scaffold-and-facade", "status": "pending" }, + { "step": 2, "name": "core-domain-dof-extraction", "status": "pending" }, + { "step": 3, "name": "math-solver-extraction", "status": "pending" }, + { "step": 4, "name": "io-parser-extraction", "status": "pending" }, + { "step": 5, "name": "results-reference-extraction", "status": "pending" }, + { "step": 6, "name": "mitc4-geometry-strain-extraction", "status": "pending" }, + { "step": 7, "name": "mitc4-material-stiffness-extraction", "status": "pending" }, + { "step": 8, "name": "assembly-analysis-extraction", "status": "pending" }, + { "step": 9, "name": "architecture-evaluator-closeout", "status": "pending" } + ] +} diff --git a/phases/1-structure-alignment-refactor/step0.md b/phases/1-structure-alignment-refactor/step0.md new file mode 100644 index 0000000..c5f6a53 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step0.md @@ -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. diff --git a/phases/1-structure-alignment-refactor/step1.md b/phases/1-structure-alignment-refactor/step1.md new file mode 100644 index 0000000..d7eeb7e --- /dev/null +++ b/phases/1-structure-alignment-refactor/step1.md @@ -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. diff --git a/phases/1-structure-alignment-refactor/step2.md b/phases/1-structure-alignment-refactor/step2.md new file mode 100644 index 0000000..01ff2eb --- /dev/null +++ b/phases/1-structure-alignment-refactor/step2.md @@ -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`. diff --git a/phases/1-structure-alignment-refactor/step3.md b/phases/1-structure-alignment-refactor/step3.md new file mode 100644 index 0000000..8fca84f --- /dev/null +++ b/phases/1-structure-alignment-refactor/step3.md @@ -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. diff --git a/phases/1-structure-alignment-refactor/step4.md b/phases/1-structure-alignment-refactor/step4.md new file mode 100644 index 0000000..8a06235 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step4.md @@ -0,0 +1,72 @@ +# Sprint Contract: IO Parser Extraction + +## Objective +Move the Abaqus Phase 1 input parser into the `IO` module while preserving the documented strict parser subset and unsupported-feature diagnostics. + +## Required Reading +- /AGENTS.md +- /PROGRESS.md +- /PLAN.md +- /docs/README.md +- /docs/HARNESS_ENGINEERING.md +- /docs/ARCHITECTURE.md +- /docs/ADR.md +- /docs/ABAQUS_INPUT_SUBSET.md +- /docs/VERIFICATION_PLAN.md +- /phases/1-structure-alignment-refactor/step0-architecture-map.md +- /phases/1-structure-alignment-refactor/step2.md + +## Scope +- Extract `KeywordLine`, `ParseResult`, `AbaqusInputParser`, and parser-only helpers into `IO`. +- Keep parser output in `Domain`. +- Preserve strict rejection for `S4R`, `Part/Assembly/Instance`, `*Include`, `NLGEOM=YES`, nonzero prescribed displacement, and unsupported keyword parameters. +- Keep normalized reference behavior for `references/quad_02_phase1.inp`. + +## Allowed Files +- `include/fesa/fesa.hpp` +- `include/fesa/IO/` +- `src/IO/` +- `include/fesa/Core/` +- `src/Core/` +- `tests/` +- `CMakeLists.txt` +- `phases/1-structure-alignment-refactor/index.json` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not add new Abaqus keyword support. +- Do not accept original `references/quad_02.inp` as a Phase 1 parser input. +- Do not change `docs/ABAQUS_INPUT_SUBSET.md` unless a purely clarifying note is required. +- Do not move results or reference comparator code in this step. + +## Tests To Write First +- Add or update an include/link test for `fesa/IO` parser headers. +- Preserve parser acceptance and rejection tests as characterization tests. +- Ensure original `quad_02.inp` unsupported provenance remains rejected where tested. + +## Reference Artifacts +- `references/quad_02.inp` +- `references/quad_02_phase1.inp` + +Do not edit these files. + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- Parser code lives in `IO` and does not own analysis or assembly behavior. +- Parser subset discipline is unchanged. +- Diagnostics still include enough source context for malformed input. +- `Domain` remains the parser output boundary. +- Stored reference compatibility notes remain true. + +## Handoff Requirements +- Update this step status in `phases/1-structure-alignment-refactor/index.json`. +- Record moved parser files and any unsupported-feature behavior verified. + +## Do Not +- Do not normalize reference files inside parser code. +- Do not silently broaden parser compatibility while refactoring. diff --git a/phases/1-structure-alignment-refactor/step5.md b/phases/1-structure-alignment-refactor/step5.md new file mode 100644 index 0000000..22abe25 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step5.md @@ -0,0 +1,72 @@ +# Sprint Contract: Results Reference Extraction + +## Objective +Move the in-memory result model, Phase 1 results writer, displacement CSV loader, and reference comparator into `Results` while preserving the documented step/frame/field schema. + +## Required Reading +- /AGENTS.md +- /PROGRESS.md +- /PLAN.md +- /docs/README.md +- /docs/HARNESS_ENGINEERING.md +- /docs/ARCHITECTURE.md +- /docs/ADR.md +- /docs/RESULTS_SCHEMA.md +- /docs/VERIFICATION_PLAN.md +- /docs/NUMERICAL_CONVENTIONS.md +- /phases/1-structure-alignment-refactor/step0-architecture-map.md +- /phases/1-structure-alignment-refactor/step2.md + +## Scope +- Extract `FieldOutput`, `ResultFrame`, `ResultStep`, `ResultFile`, `InMemoryResultsWriter`, displacement CSV tables, comparison options, and comparison results. +- Preserve mandatory Phase 1 `U` and `RF` field metadata. +- Preserve CSV mapping from Abaqus `Node Label`, `U-U1`, `U-U2`, `U-U3`, `UR-UR1`, `UR-UR2`, `UR-UR3`. +- Keep HDF5 as a future writer adapter; do not add the dependency yet. + +## Allowed Files +- `include/fesa/fesa.hpp` +- `include/fesa/Results/` +- `src/Results/` +- `include/fesa/Core/` +- `include/fesa/IO/` +- `tests/` +- `CMakeLists.txt` +- `phases/1-structure-alignment-refactor/index.json` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not add HDF5 output implementation. +- Do not change result labels, field positions, basis, or comparison tolerances. +- Do not add reaction CSV parsing in this step. +- Do not change analysis execution. + +## Tests To Write First +- Add or update include/link tests for `fesa/Results` headers. +- Preserve existing result schema, CSV loader, comparison, and `quad_02_phase1` displacement regression tests as characterization tests. + +## Reference Artifacts +- `references/quad_02_phase1.inp` +- `references/quad_02_displacements.csv` + +Do not edit these files. + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- Result model follows `docs/RESULTS_SCHEMA.md`. +- `U` and `RF` metadata are unchanged. +- CSV comparison still matches by node id, not row order alone. +- `quad_02_phase1` stored displacement regression still passes. +- HDF5 APIs do not leak into solver core. + +## Handoff Requirements +- Update this step status in `phases/1-structure-alignment-refactor/index.json`. +- Record moved result/comparator files and any remaining result symbols still left in `fesa.hpp`. + +## Do Not +- Do not relax reference tolerances to make relocation pass. +- Do not treat missing Abaqus reaction CSV as solved. diff --git a/phases/1-structure-alignment-refactor/step6.md b/phases/1-structure-alignment-refactor/step6.md new file mode 100644 index 0000000..1fa9e88 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step6.md @@ -0,0 +1,68 @@ +# Sprint Contract: MITC4 Geometry Strain Extraction + +## Objective +Move MITC4 geometry, director, natural-coordinate, displacement, direct covariant strain, and MITC shear-tying helpers into the `Element` module without changing the documented formulation. + +## 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 +- /docs/MITC4_FORMULATION.md +- /docs/VERIFICATION_PLAN.md +- /phases/1-structure-alignment-refactor/step0-architecture-map.md +- /phases/1-structure-alignment-refactor/step3.md + +## Scope +- Extract MITC4 natural points, tying points, director frames, geometry, integration basis, displacement derivative helpers, direct strain rows, and MITC shear tying rows. +- Keep the FESA/Abaqus S4 node order and tying-point labels unchanged. +- Keep diagnostics for invalid thickness, singular center normal, singular basis, and singular Jacobian. +- Keep `drilling` handling out of this step except where existing local rotation structures require it. + +## Allowed Files +- `include/fesa/fesa.hpp` +- `include/fesa/Element/` +- `src/Element/` +- `include/fesa/Core/` +- `include/fesa/Math/` +- `tests/` +- `CMakeLists.txt` +- `phases/1-structure-alignment-refactor/index.json` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not change MITC4 formulas, signs, tying interpolation, basis construction, or tolerances. +- Do not move stiffness integration or material matrix code in this step unless needed only to resolve declarations. +- Do not add S4R, reduced integration, hourglass control, pressure loads, or nonlinear geometry. + +## Tests To Write First +- Add or update include/link tests for MITC4 geometry/strain module headers. +- Preserve finite-difference, tying interpolation, geometry, basis, and diagnostic tests as characterization tests. + +## Reference Artifacts +- None. + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- MITC4 geometry/strain helpers live in `Element`. +- The implementation still matches `docs/MITC4_FORMULATION.md`. +- FESA tying point sign convention remains unchanged. +- No parser, assembly, or result behavior changes are mixed in. +- Existing MITC4 geometry and strain tests still pass. + +## Handoff Requirements +- Update this step status in `phases/1-structure-alignment-refactor/index.json`. +- Record moved MITC4 geometry/strain files and any remaining Element symbols still left in `fesa.hpp`. + +## Do Not +- Do not simplify or rewrite the formulation during relocation. +- Do not tune tests around floating-point drift unless a real relocation-induced bug is found and fixed. diff --git a/phases/1-structure-alignment-refactor/step7.md b/phases/1-structure-alignment-refactor/step7.md new file mode 100644 index 0000000..cb1affe --- /dev/null +++ b/phases/1-structure-alignment-refactor/step7.md @@ -0,0 +1,70 @@ +# Sprint Contract: MITC4 Material Stiffness Extraction + +## Objective +Move MITC4 material matrix, covariant-to-local transform, integration scaffolding, drilling stabilization, stiffness assembly, and internal force helpers into the documented `Element` and `Material` 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 +- /docs/MITC4_FORMULATION.md +- /docs/VERIFICATION_PLAN.md +- /phases/1-structure-alignment-refactor/step0-architecture-map.md +- /phases/1-structure-alignment-refactor/step6.md + +## Scope +- Extract plane-stress MITC4 material matrix helpers and material diagnostics. +- Extract `2 x 2 x 2` integration data, stiffness accumulation, local/global transform, drilling stabilization, `MITC4ElementKernel`, and internal force helpers. +- Keep `drilling_stiffness_scale = 1.0e-3` and reference-diagonal policy unchanged. +- Keep `Element` responsible for MITC4 element kernel behavior; keep reusable material-law helpers under `Material` if separated. + +## Allowed Files +- `include/fesa/fesa.hpp` +- `include/fesa/Element/` +- `src/Element/` +- `include/fesa/Material/` +- `src/Material/` +- `include/fesa/Math/` +- `tests/` +- `CMakeLists.txt` +- `phases/1-structure-alignment-refactor/index.json` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not change MITC4 stiffness formulas, drilling policy, integration order, or patch-test tolerances. +- Do not add stress/resultant output. +- Do not add reduced integration, S4R, hourglass control, nonlinear tangent stiffness, or pressure loads. +- Do not change assembly behavior beyond include dependency repair. + +## Tests To Write First +- Add or update include/link tests for MITC4 stiffness/material module headers. +- Preserve stiffness symmetry, rigid body, drilling sensitivity, internal force, patch, and locking-sensitivity tests as characterization tests. + +## Reference Artifacts +- None. + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- MITC4 material and stiffness code no longer lives in the umbrella header as implementation. +- Drilling policy matches `docs/MITC4_FORMULATION.md`. +- Element patch and locking-sensitivity tests still pass. +- No unsupported Abaqus behavior or result output is added. +- Public facade includes remain compatible. + +## Handoff Requirements +- Update this step status in `phases/1-structure-alignment-refactor/index.json`. +- Record moved MITC4 material/stiffness files and any remaining MITC4 implementation still left in `fesa.hpp`. + +## Do Not +- Do not optimize or parallelize element stiffness in this relocation step. +- Do not use reference displacement mismatch to retune formulation parameters. diff --git a/phases/1-structure-alignment-refactor/step8.md b/phases/1-structure-alignment-refactor/step8.md new file mode 100644 index 0000000..a6037d3 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step8.md @@ -0,0 +1,82 @@ +# Sprint Contract: Assembly Analysis Extraction + +## Objective +Move full-space assembly, reduced projection, reaction recovery path, analysis state/result objects, and linear static workflow into `Assembly` and `Analysis` while preserving Phase 1 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 +- /docs/RESULTS_SCHEMA.md +- /docs/MITC4_FORMULATION.md +- /docs/VERIFICATION_PLAN.md +- /phases/1-structure-alignment-refactor/step0-architecture-map.md +- /phases/1-structure-alignment-refactor/step2.md +- /phases/1-structure-alignment-refactor/step3.md +- /phases/1-structure-alignment-refactor/step5.md +- /phases/1-structure-alignment-refactor/step7.md + +## Scope +- Extract `AssemblyResult`, `ReducedSystem`, full-space assembly, reduced projection, and full-vector reaction recovery helpers into `Assembly`. +- Extract `AnalysisState`, `AnalysisResult`, `Analysis`, `LinearStaticAnalysis`, and input-to-analysis convenience workflow into `Analysis`. +- Keep Strategy + Template Method structure visible. +- Preserve `RF = K_full * U_full - F_full`. +- Preserve solver adapter injection and deterministic default solver behavior. + +## Allowed Files +- `include/fesa/fesa.hpp` +- `include/fesa/Assembly/` +- `src/Assembly/` +- `include/fesa/Analysis/` +- `src/Analysis/` +- `include/fesa/Core/` +- `include/fesa/Element/` +- `include/fesa/Math/` +- `include/fesa/Results/` +- `include/fesa/IO/` +- `tests/` +- `CMakeLists.txt` +- `phases/1-structure-alignment-refactor/index.json` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not change solve algorithms, convergence logic, boundary-condition semantics, or result schema. +- Do not add nonlinear, dynamic, heat-transfer, pressure-load, RBE, or HDF5 behavior. +- Do not compute reactions from reduced quantities. +- Do not add production sparse storage beyond the existing scaffold. + +## Tests To Write First +- Add or update include/link tests for `Assembly` and `Analysis` module headers. +- Preserve assembly, reduced solve, solver injection, full-vector RF, input-to-result workflow, and `quad_02_phase1` reference regression tests as characterization tests. + +## Reference Artifacts +- `references/quad_02_phase1.inp` +- `references/quad_02_displacements.csv` + +Do not edit these files. + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- Assembly owns full-space stiffness/load preservation and reduced projection. +- Analysis owns execution flow and state updates. +- `DofManager` remains the owner of equation numbering and full/reduced mapping. +- Full-vector RF recovery is unchanged. +- `quad_02_phase1` displacement regression still passes. + +## Handoff Requirements +- Update this step status in `phases/1-structure-alignment-refactor/index.json`. +- Record moved assembly/analysis files and any remaining production implementation still left in `fesa.hpp`. + +## Do Not +- Do not hide a behavior change under the label "refactor". +- Do not broaden Phase 1 feature scope. diff --git a/phases/1-structure-alignment-refactor/step9.md b/phases/1-structure-alignment-refactor/step9.md new file mode 100644 index 0000000..ef8e4c8 --- /dev/null +++ b/phases/1-structure-alignment-refactor/step9.md @@ -0,0 +1,70 @@ +# Sprint Contract: Architecture Evaluator Closeout + +## Objective +Independently evaluate the completed structure-alignment refactor against `docs/ARCHITECTURE.md`, persistent project guardrails, tests, reference artifacts, and phase handoff requirements. + +## 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 +- /docs/ABAQUS_INPUT_SUBSET.md +- /docs/VERIFICATION_PLAN.md +- /docs/RESULTS_SCHEMA.md +- /docs/MITC4_FORMULATION.md +- /phases/1-structure-alignment-refactor/index.json +- /phases/1-structure-alignment-refactor/step0-architecture-map.md + +## Scope +- Review the final production layout under `include/fesa/` and `src/`. +- Confirm the umbrella header is a facade, not the primary implementation body. +- Confirm source ownership matches the `src/` directory structure in `docs/ARCHITECTURE.md`. +- Run validation and inspect stored-reference regression status. +- Produce an evaluator report at `phases/1-structure-alignment-refactor/step9-evaluator-report.md`. +- Update phase status, `PLAN.md`, and `PROGRESS.md`. + +## Allowed Files +- `phases/index.json` +- `phases/1-structure-alignment-refactor/index.json` +- `phases/1-structure-alignment-refactor/step9-evaluator-report.md` +- `PLAN.md` +- `PROGRESS.md` + +## Explicit Non-Goals +- Do not implement missing refactor work in the evaluator step. +- Do not change solver behavior or tests to make evaluation pass. +- Do not claim full PRD Phase 1 completion unless R-010 and R-013 are also resolved. +- Do not approve a layout that still relies on `fesa.hpp` as the main implementation location. + +## Tests To Write First +- None. This is an evaluator-only step. + +## Reference Artifacts +- `references/quad_02_phase1.inp` +- `references/quad_02_displacements.csv` + +## Acceptance Commands +```bash +python scripts/validate_workspace.py +``` + +## Evaluator Checklist +- `src/Analysis`, `src/Assembly`, `src/Boundary`, `src/Core`, `src/Element`, `src/IO`, `src/Load`, `src/Math`, `src/Material`, `src/Property`, `src/Results`, and `src/Util` exist as needed and own their documented implementation areas. +- `include/fesa/fesa.hpp` is a compatibility facade and does not contain the bulk of production implementation. +- Public tests and direct module include tests pass. +- Parser subset, MITC4 formulation, numerical conventions, result schema, and reference comparison behavior are unchanged. +- `quad_02_phase1` stored displacement regression still passes. +- PLAN/PROGRESS clearly state any residual architecture debt. + +## Handoff Requirements +- If passed, mark `1-structure-alignment-refactor` completed in `phases/index.json`. +- If failed, write concrete findings and required fixes in `step9-evaluator-report.md` and keep the phase pending or blocked. +- Keep R-010 and R-013 visible if they remain unresolved. + +## Do Not +- Do not self-approve incomplete module separation. +- Do not let a passing compile hide architecture drift. diff --git a/phases/index.json b/phases/index.json index f75a696..9372e83 100644 --- a/phases/index.json +++ b/phases/index.json @@ -9,6 +9,10 @@ "dir": "1-linear-static-mitc4-rebaseline", "status": "completed", "completion_note": "P1R-15 evaluator closeout passed on 2026-05-04. Product-level Phase 1 reference gaps R-010 and R-013 remain tracked in PLAN.md." + }, + { + "dir": "1-structure-alignment-refactor", + "status": "pending" } ] }