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

Continue the new Phase 1 rebaseline plan in phases/1-linear-static-mitc4-rebaseline, starting with P1R-06 results model and displacement CSV comparator foundation. The old phases/1-linear-static-mitc4 path is historical and superseded by the paper-based MITC4 formulation reset.

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-linear-static-mitc4-rebaseline/index.json
16. phases/1-linear-static-mitc4/index.json for historical context only

Active Phase Files

• Active phase directory: phases/1-linear-static-mitc4-rebaseline
• Execute with: 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; step15.md is the independent evaluator closeout.
• 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-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 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	partial	Core aliases, DOF mapping, validation harness, model diagnostic context, DofManager, sparse-connectivity inputs, and full-vector reaction formula were revalidated in steps 2 and 5; results and assembly remain for steps 6 and 12.	P1R-02 and P1R-05 validation output
G4 - MITC4 element readiness	reopened	MITC4 formulation was rewritten from local papers; element implementation must be rebuilt or revalidated through steps 7 through 11.	Revised docs/MITC4_FORMULATION.md, future element tests
G5 - End-to-end solver	reopened	Linear static path must be revalidated through steps 13 and 14 after the MITC4 rebuild and quad_02 compatibility path.	Future 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
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	pending	results generator	Rebuild minimum results model and displacement CSV comparator.	none	U/RF schema tests and CSV comparator tests
P1R-07	pending	MITC4 generator	Implement MITC4 geometry, node order, tying points, directors, and local bases.	none	Shape/basis/diagnostic tests
P1R-08	pending	MITC4 generator	Implement degenerated-continuum displacement, covariant strain rows, and MITC shear tying.	P1R-07	Finite-difference and tying interpolation tests
P1R-09	pending	MITC4 generator	Implement material matrix, transform, and 2 x 2 x 2 integration scaffolding.	P1R-08	Material/integration tests
P1R-10	pending	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	pending	verification generator	Add MITC4 patch, locking-sensitivity, and benchmark tests.	P1R-10	Membrane/bending/shear/twist/locking tests
P1R-12	pending	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	pending	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	pending	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	pending	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?