# 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
Prepare FESA for Phase 1 implementation planning: a reference-verified linear static MITC4 shell solver using the documented architecture, numerical conventions, Abaqus input subset, HDF5 result schema, and stored reference artifacts.

## 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`

## Phase 1 Readiness Tasks
| ID | Status | Owner | Task | Source |
|---|---|---|---|---|
| R-004 | pending | MITC4 formulation agent | Finalize MITC4 transverse shear tying-point equations. | `docs/MITC4_FORMULATION.md` |
| R-005 | pending | MITC4 formulation agent | Finalize MITC4 local shell basis algorithm for flat and non-flat quads. | `docs/MITC4_FORMULATION.md`, `docs/NUMERICAL_CONVENTIONS.md` |
| R-006 | pending | MITC4 formulation agent | Finalize default artificial drilling stiffness scale and parameter name. | `docs/MITC4_FORMULATION.md` |
| R-007 | pending | user + architecture agent | Decide whether Phase 1 outputs only `U` and `RF`, or also `S`, `E`, and `SF`. | `docs/RESULTS_SCHEMA.md`, `docs/MITC4_FORMULATION.md` |
| R-008 | pending | user + phase planner | Decide build system; CMake is recommended unless project constraints say otherwise. | `README.md`, `docs/README.md` |
| R-009 | pending | verification agent | Define and implement the automated loader/comparator contract for `references/*_displacements.csv`. | `docs/VERIFICATION_PLAN.md`, `docs/RESULTS_SCHEMA.md` |
| 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 | pending | Readiness tasks R-004 through R-011 are completed or explicitly deferred. | Updated docs, PLAN.md, PROGRESS.md |
| G1 - Build and validation | pending | Build system, test framework, and `scripts/validate_workspace.py` run real checks. | Validation command output |
| G2 - Parser and domain | pending | Phase 1 `.inp` subset parses into `Domain`; unsupported features fail clearly. | Parser tests and diagnostics tests |
| G3 - DOF/math/results infrastructure | pending | Core types, DofManager, sparse math adapters, minimal results writer, and CSV comparator are tested. | Unit tests and schema/comparator tests |
| G4 - MITC4 element readiness | pending | MITC4 formulation open decisions are closed and element-level tests pass. | Updated formulation doc and element tests |
| G5 - End-to-end solver | pending | Linear static path writes `U`/`RF` and passes stored-reference and negative tests. | 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-00 | pending | harness sprint planner | Convert this PLAN into executable phase files with sprint contracts. | R-004..R-011 status reviewed | Phase files contain objective, scope, allowed files, tests-first plan, reference artifacts, evaluator checklist |
| P1-01 | pending | build/system generator | Establish C++ project skeleton, build system, test framework, and validation script integration. | R-008 | `python scripts/validate_workspace.py` runs build/test checks |
| P1-02 | pending | core generator | Add core numeric/id types, DOF enum, diagnostics primitives, and logging/error result conventions. | P1-01 | Tests for int64 aliases, DOF mapping, diagnostic payloads |
| P1-03 | pending | domain generator | Implement immutable-ish `Domain` entities: nodes, elements, sets, materials, shell properties, loads, boundaries, steps. | P1-02 | Tests for construction, lookup, duplicate ids, label preservation |
| P1-04 | pending | parser generator | Implement Abaqus lexical/keyword parser foundation and Phase 1 object factories/registries. | P1-03 | Parser smoke tests for supported keywords and line-numbered diagnostics |
| P1-05 | pending | parser generator | Complete `*Nset`, `*Elset`, material, shell section, boundary, cload, step/static/end-step subset behavior. | P1-04 | Supported subset tests; reject `S4R`, `NLGEOM=YES`, Part/Assembly/Instance |
| P1-06 | pending | validation generator | Implement domain validation and singular-prone pre-solve diagnostics. | P1-05 | Missing node/set/material/property/load/BC diagnostics and no-active-element tests |
| P1-07 | pending | dof generator | Implement `AnalysisModelBuilder` and `DofManager` for 6-DOF nodes, constrained/free mapping, equation numbering, sparse pattern input, and full/reduced reconstruction. | P1-06 | Exact mapping tests, constrained elimination tests, reconstruction tests |
| P1-08 | pending | math generator | Implement vector/sparse matrix/linear solver interfaces and a deterministic test solver adapter. | P1-07 | Sparse pattern tests, reduced-system solve tests, no MKL leakage into core APIs |
| P1-09 | pending | results generator | Implement minimal result model and writer boundary for `U` and `RF` step/frame/field outputs. | P1-07, P1-08 | Schema tests for ids, component labels, frame metadata, int64/double storage |
| P1-10 | pending | verification generator | Implement `references/*_displacements.csv` loader and comparator for FESA `U` output. | P1-09, R-009 | Column validation, node-id matching, abs/rel tolerance tests |
| P1-11 | pending | MITC4 formulation agent | Finalize MITC4 transverse shear tying points, local basis, integration ordering, drilling stiffness default, and Phase 1 output scope. | R-004, R-005, R-006, R-007 | `docs/MITC4_FORMULATION.md` updated and reviewed |
| P1-12 | pending | element generator | Implement MITC4 shape functions, local basis utility, element stiffness skeleton, and drilling stiffness parameter path. | P1-11, P1-08 | Shape function, derivative, 24x24 dimension, symmetry, rigid body, drilling sensitivity tests |
| P1-13 | pending | assembly generator | Implement assembly of element stiffness/load contributions into full and reduced system data while preserving full-space data for reactions. | P1-12, P1-07, P1-08 | Assembly tests and full-vector reaction recovery test |
| P1-14 | pending | analysis generator | Implement `LinearStaticAnalysis` Template Method path: build model, DOFs, sparse pattern, assemble, constrain, solve, update state, write results. | P1-09, P1-13 | End-to-end small model test with `U` and `RF` |
| P1-15 | pending | 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 | pending | 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.
- Decide first `quad_01_displacements.csv` tolerance for comparator testing.
- 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?
- What is the default drilling stiffness scale?
- Which MITC4 stress/strain/resultant outputs are mandatory in Phase 1?
- Should CMake be adopted as the first build system?
- What tolerance should be used for the first `quad_01_displacements.csv` comparison?
- Will Phase 1 `RF` be checked from Abaqus reaction CSV or from internal equilibrium tests first?