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

Resolve the remaining Phase 1 reference-artifact blockers after the P1-01 through P1-14 implementation pass: add Phase 1-compatible Abaqus TYPE=S4 displacement references and decide the first RF reference path.

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: blocked at P1-15 because no Phase 1-compatible Abaqus TYPE=S4 reference input and matching displacement CSV are available yet.

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	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	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	satisfied	MITC4 formulation open decisions are closed and element-level tests pass.	Updated formulation doc and element tests
G5 - End-to-end solver	partial	Linear static path writes U/RF; stored Phase 1-compatible Abaqus reference regression is blocked by missing artifacts.	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.

Required reference additions or decisions:

• Add at least one Phase 1-compatible TYPE=S4 linear static .inp case.
• 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?
• Will Phase 1 RF be checked from Abaqus reaction CSV or from internal equilibrium tests first?