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

Prepare FESA for Phase 1 implementation planning: a reference-verified linear static MITC4 shell solver using the documented architecture, numerical conventions, Abaqus input subset, HDF5 result schema, and stored reference artifacts.

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

Phase 1 Readiness Tasks

ID	Status	Owner	Task	Source
R-004	pending	MITC4 formulation agent	Finalize MITC4 transverse shear tying-point equations.	docs/MITC4_FORMULATION.md
R-005	pending	MITC4 formulation agent	Finalize MITC4 local shell basis algorithm for flat and non-flat quads.	docs/MITC4_FORMULATION.md, docs/NUMERICAL_CONVENTIONS.md
R-006	pending	MITC4 formulation agent	Finalize default artificial drilling stiffness scale and parameter name.	docs/MITC4_FORMULATION.md
R-007	pending	user + architecture agent	Decide whether Phase 1 outputs only U and RF, or also S, E, and SF.	docs/RESULTS_SCHEMA.md, docs/MITC4_FORMULATION.md
R-008	pending	user + phase planner	Decide build system; CMake is recommended unless project constraints say otherwise.	README.md, docs/README.md
R-009	pending	verification agent	Define and implement the automated loader/comparator contract for references/*_displacements.csv.	docs/VERIFICATION_PLAN.md, docs/RESULTS_SCHEMA.md
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-011	pending	user + Abaqus compatibility agent	Add at least one Phase 1-compatible Abaqus TYPE=S4 input case; keep quad_01.inp as stored S4R/NLGEOM reference provenance until S4R/nonlinear support is intentionally added.	docs/ABAQUS_INPUT_SUBSET.md, docs/VERIFICATION_PLAN.md

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	pending	Readiness tasks R-004 through R-011 are completed or explicitly deferred.	Updated docs, PLAN.md, PROGRESS.md
G1 - Build and validation	pending	Build system, test framework, and scripts/validate_workspace.py run real checks.	Validation command output
G2 - Parser and domain	pending	Phase 1 .inp subset parses into Domain; unsupported features fail clearly.	Parser tests and diagnostics tests
G3 - DOF/math/results infrastructure	pending	Core types, DofManager, sparse math adapters, minimal results writer, and CSV comparator are tested.	Unit tests and schema/comparator tests
G4 - MITC4 element readiness	pending	MITC4 formulation open decisions are closed and element-level tests pass.	Updated formulation doc and element tests
G5 - End-to-end solver	pending	Linear static path writes U/RF and passes stored-reference and negative tests.	Integration/reference regression 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
P1-00	pending	harness sprint planner	Convert this PLAN into executable phase files with sprint contracts.	R-004..R-011 status reviewed	Phase files contain objective, scope, allowed files, tests-first plan, reference artifacts, evaluator checklist
P1-01	pending	build/system generator	Establish C++ project skeleton, build system, test framework, and validation script integration.	R-008	python scripts/validate_workspace.py runs build/test checks
P1-02	pending	core generator	Add core numeric/id types, DOF enum, diagnostics primitives, and logging/error result conventions.	P1-01	Tests for int64 aliases, DOF mapping, diagnostic payloads
P1-03	pending	domain generator	Implement immutable-ish Domain entities: nodes, elements, sets, materials, shell properties, loads, boundaries, steps.	P1-02	Tests for construction, lookup, duplicate ids, label preservation
P1-04	pending	parser generator	Implement Abaqus lexical/keyword parser foundation and Phase 1 object factories/registries.	P1-03	Parser smoke tests for supported keywords and line-numbered diagnostics
P1-05	pending	parser generator	Complete *Nset, *Elset, material, shell section, boundary, cload, step/static/end-step subset behavior.	P1-04	Supported subset tests; reject S4R, NLGEOM=YES, Part/Assembly/Instance
P1-06	pending	validation generator	Implement domain validation and singular-prone pre-solve diagnostics.	P1-05	Missing node/set/material/property/load/BC diagnostics and no-active-element tests
P1-07	pending	dof generator	Implement AnalysisModelBuilder and DofManager for 6-DOF nodes, constrained/free mapping, equation numbering, sparse pattern input, and full/reduced reconstruction.	P1-06	Exact mapping tests, constrained elimination tests, reconstruction tests
P1-08	pending	math generator	Implement vector/sparse matrix/linear solver interfaces and a deterministic test solver adapter.	P1-07	Sparse pattern tests, reduced-system solve tests, no MKL leakage into core APIs
P1-09	pending	results generator	Implement minimal result model and writer boundary for U and RF step/frame/field outputs.	P1-07, P1-08	Schema tests for ids, component labels, frame metadata, int64/double storage
P1-10	pending	verification generator	Implement references/*_displacements.csv loader and comparator for FESA U output.	P1-09, R-009	Column validation, node-id matching, abs/rel tolerance tests
P1-11	pending	MITC4 formulation agent	Finalize MITC4 transverse shear tying points, local basis, integration ordering, drilling stiffness default, and Phase 1 output scope.	R-004, R-005, R-006, R-007	docs/MITC4_FORMULATION.md updated and reviewed
P1-12	pending	element generator	Implement MITC4 shape functions, local basis utility, element stiffness skeleton, and drilling stiffness parameter path.	P1-11, P1-08	Shape function, derivative, 24x24 dimension, symmetry, rigid body, drilling sensitivity tests
P1-13	pending	assembly generator	Implement assembly of element stiffness/load contributions into full and reduced system data while preserving full-space data for reactions.	P1-12, P1-07, P1-08	Assembly tests and full-vector reaction recovery test
P1-14	pending	analysis generator	Implement LinearStaticAnalysis Template Method path: build model, DOFs, sparse pattern, assemble, constrain, solve, update state, write results.	P1-09, P1-13	End-to-end small model test with U and RF
P1-15	pending	verification generator	Add stored-reference regression suite using accepted Phase 1-compatible cases and quad_01 compatibility notes.	P1-10, P1-14, R-011	At least one displacement CSV comparison; unsupported quad_01.inp is not treated as Phase 1 support
P1-16	pending	evaluator	Run full Phase 1 evaluator pass and close documentation/handoff gaps.	P1-15	Harness evaluator report, updated PROGRESS.md, remaining Phase 2 items recorded in PLAN.md

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.

Required reference additions or decisions:

• Add at least one Phase 1-compatible TYPE=S4 linear static .inp case.
• Decide first quad_01_displacements.csv tolerance for comparator testing.
• 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 use quad_01.inp to justify S4R, Part/Assembly/Instance, or NLGEOM=YES support.
• 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 before readiness tasks are addressed.
• 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?
• What is the default drilling stiffness scale?
• Which MITC4 stress/strain/resultant outputs are mandatory in Phase 1?
• Should CMake be adopted as the first build system?
• What tolerance should be used for the first quad_01_displacements.csv comparison?
• Will Phase 1 RF be checked from Abaqus reaction CSV or from internal equilibrium tests first?