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-09 material matrix, transform, and `2 x 2 x 2` integration scaffolding. 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; `step6.md` is complete and revalidated the minimum result model plus displacement CSV comparator; `step7.md` is complete and revalidated MITC4 natural coordinates, tying points, center directors, and integration bases; `step8.md` is complete and revalidated degenerated-continuum displacement, direct covariant strain rows, and MITC shear tying rows; `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, full-vector reaction formula, result model metadata, and displacement CSV comparator were revalidated in steps 2, 5, and 6; assembly remains for step 12. | P1R-02, P1R-05, and P1R-06 validation output |
| G4 - MITC4 element readiness | partial | MITC4 formulation was rewritten from local papers; Steps 7 and 8 rebuilt geometry/director/local-basis scaffolding, displacement interpolation, direct covariant strain rows, and MITC shear tying rows, while material/integration, stiffness/drilling, and patch benchmarks remain for steps 9 through 11. | P1R-07 and P1R-08 validation output; 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 | completed | results generator | Rebuild minimum results model and displacement CSV comparator. | none | U/RF schema tests and CSV comparator tests |
| P1R-07 | completed | MITC4 generator | Implement MITC4 geometry, node order, tying points, directors, and local bases. | none | Shape/basis/diagnostic tests |
| P1R-08 | completed | 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?