# Step 3: nonlinear-mitc4-kinematics-and-recovery

## 읽어야 할 파일

- `AGENTS.md`
- `docs/ARCHITECTURE.md`
- `docs/ADR.md`
- `docs/nonlinear-static-newton-raphson/formulation.md`
- `docs/nonlinear-static-newton-raphson/numerical-review.md`
- `docs/nonlinear-static-newton-raphson/io.md`
- `include/fesa/elements/mitc4_shell.h`
- `src/fesa/elements/mitc4_shell.cpp`
- `tests/unit/elements/mitc4_shell_test.cpp`
- `include/fesa/model/shell_geometry.h`
- `src/fesa/model/shell_geometry.cpp`
- `include/fesa/model/model_types.h`
- `include/fesa/results/result_records.h`
- Step 2 files: `include/fesa/elements/finite_rotation.h`, `src/fesa/elements/finite_rotation.cpp`

## 이전 Step 전제

Step 2 provides finite rotation state and SO(3) Jacobian helpers.

## 소유 파일

- Create: `include/fesa/elements/nonlinear_mitc4_shell.h`
- Create: `src/fesa/elements/nonlinear_mitc4_shell.cpp`
- Create: `tests/unit/elements/nonlinear_mitc4_shell_test.cpp`
- Modify: `src/fesa/CMakeLists.txt`
- Modify: `tests/CMakeLists.txt`

## 인터페이스

```cpp
namespace fesa {

struct NonlinearMitc4TrialDofs {
  std::array<Vector3, 4> displacement;
  std::array<Vector3, 4> rotation_vector;
};

struct NonlinearMitc4RecoveryPoint {
  ShellMidsurfaceLocation location;
  std::array<double, 2> natural_coordinates;
  Mitc4LocalFrame local_frame;
  std::array<double, 8> generalized_strain;
  std::array<double, 8> section_resultant;
  std::array<ShellSectionStressRow, 3> stress;
};

struct NonlinearMitc4Recovery {
  std::array<NonlinearMitc4RecoveryPoint, 4> gauss_points;
  double physical_strain_energy;
};

class NonlinearMitc4Shell {
 public:
  static Result<NonlinearMitc4Shell> Create(
      std::array<const Node*, 4> nodes,
      std::array<ShellNodeInitialFrame, 4> initial_frames,
      const ShellSection& section,
      const LinearElasticMaterial& material);

  Result<NonlinearMitc4Recovery> EvaluateKinematics(
      const NonlinearMitc4TrialDofs& trial) const;
  Result<NonlinearMitc4Recovery> RecoverState(
      const NonlinearMitc4TrialDofs& trial) const;
};

}  // namespace fesa
```

## RED

Add tests first.

- `NSNR-ELEM-KIN-001`: initial undeformed state produces zero generalized strain and zero material stress.
- `NSNR-ELEM-KIN-001A`: `NonlinearMitc4Shell::Create` requires exactly four `Node` pointers, four corresponding `ShellNodeInitialFrame` records, one `ShellSection`, and one `LinearElasticMaterial`; invalid or mismatched inputs fail closed.
- `NSNR-ELEM-KIN-002`: fixed-initial Total Lagrangian geometry uses initial midsurface and initial directors.
- `NSNR-ELEM-KIN-003`: current director interpolation for strain uses unnormalized interpolated director where formulation requires it.
- `NSNR-ELEM-KIN-004`: opposed or degenerate director state fails closed.
- `NSNR-ELEM-KIN-005`: small-rotation linear limit matches existing `Mitc4Shell` recovery within numerical-review tolerance.
- `NSNR-ELEM-KIN-006`: finite rigid translation/rotation produces objective zero physical strain/stress.
- `NSNR-ELEM-KIN-007`: recovery emits exactly four midsurface Gauss rows in `ShellMidsurfaceLocation` order; each row has generalized strain `[E11,E22,2E12,K11,K22,2K12,G13,G23]`, section resultant `[N11,N22,N12,M11,M22,M12,Q13,Q23]`, and stress positions `[BOTTOM,MIDDLE,TOP]` with components `[S11,S22,S12]`.
- `NSNR-ELEM-KIN-008`: recovery emits no S33, S13, S23 and no nodal extrapolated/corner/averaged stress.

Run:

```powershell
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "NonlinearMitc4Shell|NonlinearMitc4Recovery" --output-on-failure
```

Expected: compile or test failure because nonlinear MITC4 files do not exist. Unexpected pass stops.

## GREEN

Implement nonlinear MITC4 creation, kinematics, and recovery using approved 2x2x2 integration, MITC4 edge-midpoint shear tying, initial shell frames, homogeneous isotropic materially linear response, fixed-size row shapes, and source-order recovery rows.

## VERIFY

```powershell
cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "NonlinearMitc4Shell|NonlinearMitc4Recovery" --output-on-failure
ctest --preset windows-msvc-ninja-debug --show-only=json-v1
ctest --preset windows-msvc-ninja-debug --output-on-failure
```

Use the ignored `.harness/config.json` preset contract. The Harness process must inherit VsDevCmd x64 and `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, and `HDF5_DIR` from its parent launch environment.

## 상태 기록

Update only Step 3 status and one-line result payload. Executor owns timestamps, commits, retry, and advancement.

## 금지사항

- Do not change existing `Mitc4Shell` behavior. 이유: linear MITC4 reference regression must remain stable.
- Do not create stress quantities outside approved schema. 이유: I/O excludes S33/S13/S23 and nodal stress projections.
- Do not add residual/tangent solve logic here. 이유: Step 4 owns residual and tangent.