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

Rebaseline Phase 1 before any more implementation: use the revised docs/MITC4_FORMULATION.md as the MITC4 gate, decide how references/quad_02.inp should be handled despite its Part/Assembly/Instance structure, and draft new sprint contracts before reworking the solver.

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/index.json

Active Phase Files

• Phase directory: phases/1-linear-static-mitc4
• Execute with: python scripts/execute.py 1-linear-static-mitc4
• Step numbering is zero-based for the harness: step0.md corresponds to milestone P1-01, and step15.md corresponds to milestone P1-16.
• Every step file contains a sprint contract with objective, scope, allowed files, tests-first plan, reference-artifact policy, evaluator checklist, acceptance command, and handoff requirements.
• Current phase status: rebaseline required. Do not resume the old P1-15/P1-16 path until new contracts are drafted against the revised MITC4 formulation and the quad_02 compatibility decision.

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-011	partial	user + Abaqus compatibility agent	Review references/quad_02.inp and references/quad_02_displacements.csv: TYPE=S4 is now available, but the input includes Part/Assembly/Instance, so decide whether to normalize the file into the current flat keyword subset or add a dedicated parser sprint.	docs/ABAQUS_INPUT_SUBSET.md, docs/VERIFICATION_PLAN.md, docs/MITC4_FORMULATION.md
R-012	pending	planner + evaluator	Draft a Phase 1 redo plan and step contracts that replace or supersede the old P1-01 through P1-16 implementation path where it conflicts with the revised MITC4 formulation.	docs/HARNESS_ENGINEERING.md, docs/MITC4_FORMULATION.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 tasks R-010 and R-011 remain open; earlier formulation/build/comparator blockers are resolved.	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	Phase 1 .inp subset parses into Domain; unsupported features fail clearly.	Parser tests and diagnostics tests
G3 - DOF/math/results infrastructure	satisfied	Core types, DofManager, sparse math adapters, minimal results writer, and CSV comparator are tested.	Unit tests and schema/comparator tests
G4 - MITC4 element readiness	reopened	MITC4 formulation was rewritten from local papers; the existing element tests must be reassessed and expanded before implementation is trusted.	Revised docs/MITC4_FORMULATION.md, future element tests
G5 - End-to-end solver	reopened	Linear static path must be revalidated after the MITC4 rebuild and after the quad_02 compatibility path is decided.	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
P1-15	blocked	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	blocked	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.
• 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.

Required reference additions or decisions:

• Decide whether quad_02.inp is normalized into the current Phase 1 keyword subset or used to justify a dedicated Abaqus/CAE Part/Assembly/Instance parser sprint.
• 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 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?
• Will Phase 1 RF be checked from Abaqus reaction CSV or from internal equilibrium tests first?