# Step 4: nonlinear-mitc4-residual-and-tangent

## 읽어야 할 파일

- `AGENTS.md`
- `docs/ARCHITECTURE.md`
- `docs/ADR.md`
- `docs/nonlinear-static-newton-raphson/formulation.md`
- `docs/nonlinear-static-newton-raphson/numerical-review.md`
- `include/fesa/elements/nonlinear_mitc4_shell.h`
- `src/fesa/elements/nonlinear_mitc4_shell.cpp`
- `tests/unit/elements/nonlinear_mitc4_shell_test.cpp`
- Step 2 files: `include/fesa/elements/finite_rotation.h`
- Step 3 files: `include/fesa/elements/nonlinear_mitc4_shell.h`

## 이전 Step 전제

Step 3 provides nonlinear MITC4 creation, kinematics, and recovery rows.

## 소유 파일

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

## 인터페이스

```cpp
namespace fesa {

struct NonlinearMitc4InternalEquilibrium {
  Vector internal_residual;
  Matrix internal_tangent;
  Vector internal_force;
  NonlinearMitc4Recovery recovery;
  double physical_strain_energy;
};

Result<NonlinearMitc4InternalEquilibrium> EvaluateInternalResidualAndTangent(
    const NonlinearMitc4Shell& element,
    const NonlinearMitc4TrialDofs& trial);

}  // namespace fesa
```

## RED

Add tests first.

- `NSNR-ELEM-TAN-001`: residual and tangent are evaluated at the same trial state.
- `NSNR-ELEM-TAN-002`: directional derivative schedule uses `h={1e-3,3e-4,1e-4,3e-5,1e-5,3e-6,1e-6,3e-7}` and requires at least two observed orders `>=1.5`.
- `NSNR-ELEM-TAN-003`: one interior scaled derivative error is `<=1e-6`.
- `NSNR-ELEM-TAN-004`: zero analytical directions produce scaled absolute error `<=1e-10`.
- `NSNR-ELEM-TAN-005`: no-moment tangent satisfies scaled Frobenius symmetry `<=1e-12` after `Dq^T K_T Dq`.
- `NSNR-ELEM-TAN-006`: internal tangent contains no external fixed-load contribution; applying the same element to two incident-element load-sharing scenarios does not change internal residual/tangent.
- `NSNR-ELEM-TAN-007`: finite rigid motion keeps physical residual/objectivity invariants.
- `NSNR-ELEM-TAN-008`: patch/sign recovery identities pass relative `<=1e-9`.
- `NSNR-ELEM-TAN-009`: nonfinite trial/residual/tangent data fails closed.

Run:

```powershell
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "NonlinearMitc4Residual|NonlinearMitc4Tangent|NonlinearMitc4Objectivity|NonlinearMitc4Patch" --output-on-failure
```

Expected: new tests fail. Unexpected pass stops.

## GREEN

Implement same-trial internal residual/tangent, exact rotation derivative terms through `J_l`, map Hessian terms, objective drilling contribution, and physical recovery in the element-local contract. External CLOAD vector and tangent are not element inputs and are assembled globally in Step 5.

## VERIFY

```powershell
cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "NonlinearMitc4Residual|NonlinearMitc4Tangent|NonlinearMitc4Objectivity|NonlinearMitc4Patch" --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 4 status and one-line payload. Executor owns timestamps, commits, retry, and advancement.

## 금지사항

- Do not symmetrize the internal tangent as a cleanup step. 이유: derivative and symmetry tests must observe the mathematically assembled operator; Step 5 owns external moment tangent nonsymmetry.
- Do not add solver factorization in this Step. 이유: Step 6 owns tangent solver backend.
- Do not pass nodal CLOAD force or moment into each incident element. 이유: it duplicates source-node loads; Step 5 owns global-once external assembly.
- Do not claim Abaqus internal equivalence. 이유: FESA only uses Abaqus CSV as external numeric reference.