FESADev/PLAN.md

PLAN

Purpose

PLAN.md is the shared forward-looking work plan for FESA agents.

Every new agent session must read this file together with PROGRESS.md before planning or editing. Keep this file focused on what should happen next, not on long historical notes.

How To Use

• Update this file when project priorities, planned phases, task ownership, or open decisions change.
• Keep tasks concrete enough that another agent can continue without private context.
• Link to the owning design document for each task when possible.
• Do not mark work complete here. Move completion notes to PROGRESS.md.
• If an item becomes obsolete, move it to PROGRESS.md with a short reason instead of silently deleting it.

Current Objective

Execute the Phase 1 structure-alignment refactor in phases/1-structure-alignment-refactor, continuing with P1A-07 MITC4 material/stiffness extraction. P1A-00 completed the architecture drift audit, P1A-01 created the module scaffold, P1A-02 extracted Core/Util plus Phase 1 Boundary/Load/Property model ownership, P1A-03 extracted Math primitives plus the solver adapter boundary, P1A-04 extracted the Abaqus Phase 1 parser into IO, P1A-05 extracted Results/reference comparison, and P1A-06 extracted MITC4 geometry/strain helpers into Element without changing solver behavior. 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
2. PROGRESS.md
3. PLAN.md
4. docs/README.md
5. docs/HARNESS_ENGINEERING.md
6. docs/PRD.md
7. docs/ARCHITECTURE.md
8. docs/ADR.md
9. docs/NUMERICAL_CONVENTIONS.md
10. docs/ABAQUS_INPUT_SUBSET.md
11. docs/VERIFICATION_PLAN.md
12. docs/RESULTS_SCHEMA.md
13. docs/MITC4_FORMULATION.md
14. phases/index.json
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 is complete and wrote phases/1-structure-alignment-refactor/step0-architecture-map.md; step1.md is complete and created module scaffold headers, source directories, CMake source discovery, and umbrella compatibility smoke coverage; step2.md is complete and extracted Core/Util domain, diagnostics, DofManager ownership, AnalysisModel/AnalysisState, and Phase 1 Boundary/Load/Property model ownership; step3.md is complete and extracted Math primitives, sparse pattern data, dense matrix support, and solver adapter boundary; step4.md is complete and extracted the Abaqus parser into IO; step5.md is complete and extracted Results/reference comparison code; step6.md is complete and extracted 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.
• Every step file contains a sprint contract with objective, required reading, scope, allowed files, explicit non-goals, tests to write first, reference artifacts, acceptance command, evaluator checklist, and handoff requirements.
• Historical phase directory: phases/1-linear-static-mitc4
• Historical phase status: blocked/superseded. Do not resume the old P1-15/P1-16 path unless the user explicitly requests recovery of that exact phase.

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	completed	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	completed	generator	Create module directory scaffold, CMake source boundaries, and umbrella facade policy.	P1A-00	Module include smoke tests and build stability
P1A-02	completed	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	completed	generator	Extract Math and solver adapter boundaries.	P1A-02	Linear solver interface remains adapter-ready; int64 paths unchanged
P1A-04	completed	generator	Extract Abaqus parser into IO.	P1A-02	Parser subset and unsupported-feature diagnostics unchanged
P1A-05	completed	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	completed	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.

Required capabilities:

• Parse the Phase 1 Abaqus input subset into Domain: *Node, *Element, *Nset, *Elset, *Material, *Elastic, *Shell Section, *Boundary, *Cload, *Step, *Static, *End Step.
• Reject unsupported features with diagnostics, including S4R, Part/Assembly/Instance, *Include, pressure loads, nonzero prescribed displacement, and NLGEOM=YES.
• Build AnalysisModel for one active linear static step.
• Manage six shell DOFs per node with DofManager: UX, UY, UZ, RX, RY, RZ.
• Apply fixed boundary conditions by constrained DOF elimination.
• Assemble a sparse global linear system with int64 ids/indices/equation numbers and double values.
• Solve the reduced free-DOF system through a solver interface that can later bind to MKL.
• Reconstruct full vectors and recover RF = K_full * U_full - F_full.
• Write minimum Phase 1 results: model ids/connectivity plus U and RF in the documented step/frame/field layout.
• Compare U against stored references/*_displacements.csv artifacts.
• Provide singular system diagnostics for missing constraints, missing properties/materials, invalid references, untouched free DOFs, and solver singularity.
• Pass unit, integration, reference, and negative tests required by docs/VERIFICATION_PLAN.md.

Out of scope:

• Abaqus S4R execution semantics, hourglass control, pressure loads, RBE2/RBE3, nonzero prescribed displacements, geometric/material nonlinearity, dynamics, heat transfer, composite sections, and mesh quality diagnostics.

Phase 1 Execution Gates

Each gate should be satisfied before moving to the next implementation band unless the user explicitly accepts a documented deferral.

Gate	Status	Requirement	Evidence
G0 - Planning readiness	partial	Readiness task R-011 is resolved by quad_02_phase1.inp; R-010 and R-013 remain open.	Updated docs, PLAN.md, PROGRESS.md
G1 - Build and validation	satisfied	Build system, test framework, and scripts/validate_workspace.py run real checks.	Validation command output
G2 - Parser and domain	satisfied	Parser subset revalidated in step 3; validation and singular diagnostics revalidated in step 4.	Parser acceptance/rejection tests, validation negative tests, and validation output
G3 - DOF/math/results infrastructure	satisfied	Core aliases, DOF mapping, validation harness, model diagnostic context, DofManager, sparse-connectivity inputs, full-vector reaction formula, result model metadata, displacement CSV comparator, full-space assembly, reduced projection, sparse-pattern scaffold, and solver adapter boundary were revalidated in steps 2, 5, 6, and 12.	P1R-02, P1R-05, P1R-06, and P1R-12 validation output
G4 - MITC4 element readiness	satisfied	MITC4 formulation was rewritten from local papers; Steps 7 through 11 rebuilt geometry/director/local-basis scaffolding, displacement interpolation, direct covariant strain rows, MITC shear tying rows, plane-stress material, convected-to-local transform, 2 x 2 x 2 material integration scaffolding, stiffness/internal force, six-DOF transform, drilling stabilization, and patch/locking-sensitivity tests.	P1R-07 through P1R-11 validation output
G5 - End-to-end solver	satisfied-with-gap	Linear static input-to-result workflow is revalidated through step 13, quad_02_phase1 stored displacement regression passes in step 14, and the rebaseline evaluator closeout passed in step 15. The broader PRD target of three stored references remains open in R-013.	P1R-13 through P1R-15 validation output

Phase 1 Implementation Milestones

All milestones are intended to become one or more self-contained sprint contracts or phases/{phase}/stepN.md files. Each sprint must follow docs/HARNESS_ENGINEERING.md and be evaluated independently.

ID	Status	Owner	Objective	Depends On	Acceptance Focus
P1R-03	completed	parser generator	Revalidate Phase 1 parser and immutable Domain subset.	none	Supported keywords accepted; unsupported features rejected
P1R-04	completed	validation generator	Rebuild validation and singular diagnostic coverage.	P1R-03	Missing-reference and singular-prone negative tests
P1R-05	completed	DOF generator	Rebuild six-DOF DofManager, constrained/free mapping, equation numbering, and full-vector reconstruction.	none	DOF mapping and reaction foundation tests
P1R-06	completed	results generator	Rebuild minimum results model and displacement CSV comparator.	none	U/RF schema tests and CSV comparator tests
P1R-07	completed	MITC4 generator	Implement MITC4 geometry, node order, tying points, directors, and local bases.	none	Shape/basis/diagnostic tests
P1R-08	completed	MITC4 generator	Implement degenerated-continuum displacement, covariant strain rows, and MITC shear tying.	P1R-07	Finite-difference and tying interpolation tests
P1R-09	completed	MITC4 generator	Implement material matrix, transform, and 2 x 2 x 2 integration scaffolding.	P1R-08	Material/integration tests
P1R-10	completed	MITC4 generator	Assemble MITC4 stiffness/internal force with six-DOF transform and drilling stabilization.	P1R-09, P1R-05	Symmetry, rigid body, drilling sensitivity tests
P1R-11	completed	verification generator	Add MITC4 patch, locking-sensitivity, and benchmark tests.	P1R-10	Membrane/bending/shear/twist/locking tests
P1R-12	completed	assembly generator	Rebuild assembly, solver adapter boundary, constrained solve, and full-vector RF recovery.	P1R-05, P1R-10	Assembly and full-vector reaction tests
P1R-13	completed	analysis generator	Rebuild linear static workflow from input to U/RF result fields.	P1R-03, P1R-04, P1R-06, P1R-12	End-to-end linear static tests
P1R-14	completed	reference generator	Run stored reference displacement regression using accepted Phase 1-compatible S4 cases.	P1R-13	At least one automated CSV displacement regression
P1R-15	completed	evaluator	Independent Phase 1 evaluator closeout.	P1R-14	Pass/fail report, synchronized PLAN/PROGRESS

Phase 1 Sprint Contract Rules

Every implementation milestone above must be decomposed into one or more contracts before code changes begin.

Contract requirements:

• One contract should usually touch one layer or one module.
• Each contract must list allowed files and explicit non-goals.
• Each contract must list tests to write before implementation.
• Each contract must state whether it uses references/*.inp or references/*_displacements.csv.
• Each contract must include python scripts/validate_workspace.py plus any focused test command available after P1-01.
• Each contract must include an evaluator checklist tied to the milestone acceptance focus.
• Generator work must not begin if the contract relies on unresolved MITC4 formulas or undocumented reference tolerances.

Phase 1 Verification Strategy

Verification should grow with the implementation bands:

1. Unit tests: core types, DOF enum, diagnostics, parser tokens, label handling.
2. Parser tests: supported keywords, generated sets, duplicate/missing references, unsupported keyword diagnostics.
3. DOF/math tests: constrained/free partition, equation numbering, sparse pattern, reduced solve, full reconstruction.
4. Results tests: HDF5 or writer boundary schema for U and RF; component labels and frame metadata.
5. Reference comparator tests: CSV header validation, node matching, tolerance pass/fail behavior.
6. Element tests: MITC4 shape functions, stiffness symmetry, rigid body behavior, drilling stiffness sensitivity.
7. Assembly/analysis tests: small known systems, full-vector reaction recovery, singular negative cases.
8. Stored-reference tests: at least one Phase 1-compatible displacement CSV comparison first, then three accepted stored cases for Phase 1 completion.

Phase 1 Reference Plan

Current reference state:

• references/quad_01.inp and references/quad_01_displacements.csv are accepted stored artifacts.
• quad_01.inp contains S4R, Part/Assembly/Instance, *Density, and NLGEOM=YES; it is not a Phase 1 parser acceptance case as-is.
• references/quad_02.inp and references/quad_02_displacements.csv have been added by the user as an S4 reference pair.
• quad_02.inp uses TYPE=S4, but also includes Part/Assembly/Instance; this is a compatibility decision point, not automatic parser scope expansion.
• references/quad_02_phase1.inp is the accepted normalized Phase 1-compatible derivative input for the quad_02 S4 reference pair.

Required reference additions or decisions:

• Add *_reactions.csv or explicitly use internal equilibrium tests for Phase 1 RF until Abaqus RF output is available.
• Add more small cases until Phase 1 can pass one single-element case, one simple multi-element plate/shell case, and one curved shell benchmark.

Phase 1 Risk Controls

• Do not implement MITC4 element stiffness until the formulation gate in docs/MITC4_FORMULATION.md is closed.
• Do not treat the previous P1-01 through P1-14 implementation as authoritative after the MITC4 formulation reset.
• Do not use quad_01.inp to justify S4R, Part/Assembly/Instance, or NLGEOM=YES support.
• Do not use quad_02.inp to silently justify Part/Assembly/Instance support without a parser contract.
• Do not compute reactions from reduced vectors only.
• Do not expose MKL, TBB, or HDF5 APIs directly in solver core.
• Do not narrow ids, equation numbers, or sparse indices below int64.
• Do not allow Node or Element to own global equation ids.
• Do not treat a passing build as Phase 1 validation without parser, DOF, reference, and singular negative tests.

Current Non-Goals

• Do not implement solver code outside the matching rebaseline sprint contract.
• Do not require Abaqus execution locally or in CI.
• Do not add mesh quality diagnostics in Phase 1.
• Do not support Abaqus S4R in Phase 1.
• Do not silently expand the Abaqus input subset beyond docs/ABAQUS_INPUT_SUBSET.md.

Codex Extension Follow-up Tasks

ID	Status	Owner	Task	Source
C-002	pending	user + Codex	Confirm hook behavior in the actual Codex runtime on native Windows after features.codex_hooks is enabled.	.codex/hooks.json, .codex/hooks/*.py
C-003	pending	user + Codex	Decide whether any .codex/skills/* should be mirrored under .agents/skills/ for environments that only scan the default skill folders.	.codex/config.toml, .codex/skills/
C-004	pending	user + Codex	Confirm that the fesa-commands repo plugin appears in the active Codex plugin/command surface after marketplace registration.	plugins/fesa-commands/, .agents/plugins/marketplace.json

Open Questions

• Which Abaqus version will generate reference artifacts?
• Will Phase 1 RF be checked from Abaqus reaction CSV or from internal equilibrium tests first?