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?