FESADev/phases/shell-surface-pressure-load/step5.md

# Step 5: integrate-nonlinear-follower-pressure

## 실행 범위와 상태 소유권

이 Step의 단일 책임은 current-configuration follower pressure force와 generally nonsymmetric exact external tangent를 nonlinear full-Newton trial/commit lifecycle과 existing schema-1 output에 연결하는 것이다. Same Step에서 test-first RED, expected failure, minimal GREEN and focused VERIFY를 완료한 뒤 종료하며, automatic Stop hook이 exactly one whole-project full verification을 소유한다.

Implementation Agent는 Executor-selected Step 5만 수행하고 Step 5 `status`와 한 줄 `summary`/`error_message`/`blocked_reason`만 기록한다. Executor가 branch, retry, timestamps, commits, advancement, top-level status and output JSON을 소유한다.

## 읽어야 할 파일

- `AGENTS.md`
- `docs/ARCHITECTURE.md`
- `docs/ADR.md`
- `docs/CODINGSTYLE.md`
- `docs/HARNESS.md`
- `docs/HARNESS_WORKFLOW.md`
- `.codex/hooks.json`
- `docs/shell-surface-pressure-load/requirements.md`
- `docs/shell-surface-pressure-load/formulation.md` §§9.2–9.4, 11–14
- `docs/shell-surface-pressure-load/numerical-review.md` §6 nonlinear suite
- `docs/shell-surface-pressure-load/io.md` §§6–7, 9–10
- `docs/shell-surface-pressure-load/implementation-plan.md`
- Prior outputs: `include/fesa/model/model_types.h`, `include/fesa/model/domain.h`, `src/fesa/model/domain.cpp`, `include/fesa/analysis/analysis_model.h`, `src/fesa/analysis/analysis_model.cpp`
- Prior evaluator/assembler: `include/fesa/loads/shell_surface_pressure.h`, `src/fesa/loads/shell_surface_pressure.cpp`, `include/fesa/assembly/surface_pressure_assembler.h`, `src/fesa/assembly/surface_pressure_assembler.cpp`, their unit tests
- `include/fesa/analysis/nonlinear_static_control.h`
- `src/fesa/analysis/nonlinear_static_control.cpp`
- `include/fesa/analysis/nonlinear_static_procedure.h`
- `src/fesa/analysis/nonlinear_static_procedure.cpp`
- `include/fesa/analysis/nonlinear_analysis_state.h`
- `src/fesa/analysis/nonlinear_analysis_state.cpp`
- `include/fesa/elements/nonlinear_mitc4_shell.h`
- `src/fesa/elements/nonlinear_mitc4_shell.cpp`
- `include/fesa/solvers/linear/tangent_solver.h`
- `include/fesa/solvers/linear/mkl_pardiso_tangent_solver.h`
- `src/fesa/solvers/linear/mkl_pardiso_tangent_solver.cpp`
- `include/fesa/io/hdf5/nonlinear_hdf5_results_writer.h`
- `src/fesa/io/hdf5/nonlinear_hdf5_results_writer.cpp`
- `src/fesa/io/hdf5/hdf5_self_check.h`
- `src/fesa/io/hdf5/hdf5_self_check.cpp`
- `include/fesa/analysis/prepared_analysis.h`
- `src/fesa/analysis/prepared_analysis.cpp`
- `src/fesa/app/fesa_application.cpp`
- `tests/integration/analysis/nonlinear_static_procedure_test.cpp`
- `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp`
- `tests/unit/solvers/linear/tangent_solver_test.cpp`
- `tests/integration/app/shell_surface_pressure_application_test.cpp`
- `tests/CMakeLists.txt`

Step 4 must already provide a validated full-space assembler and linear path. Do not change its reference-configuration semantics.

## 소유 파일과 procedure contract

- Create test first: `tests/integration/analysis/shell_surface_pressure_nonlinear_test.cpp`
- Modify test first: `tests/integration/app/shell_surface_pressure_application_test.cpp`
- Modify test assertions: `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp`
- Modify: `src/fesa/analysis/nonlinear_static_procedure.cpp`
- Modify only if checked contribution composition requires a helper: `include/fesa/analysis/nonlinear_static_control.h`, `src/fesa/analysis/nonlinear_static_control.cpp`
- Modify: `tests/CMakeLists.txt`

Existing PARDISO, HDF5 writer/self-check and application production files are expected no-change verification targets unless RED proves a direct approved-contract defect.

For each Newton trial, use the existing Step 4 interface:

```cpp
Result<SurfacePressureAssemblyCandidate> AssembleSurfacePressure(
    const AnalysisModel& model,
    const DofManager& dofs,
    const Vector& full_generalized_coordinates,
    double load_factor,
    SurfacePressureConfiguration configuration,
    const ParallelFor& parallel_for);
```

Evaluate internal and external candidates at the same trial. Compose
`f_ext=f_fixed+f_pressure`, `K_ext=K_fixed+K_pressure`, `r=f_int-f_ext`, `K=K_int-K_ext`. Use the existing full-CSR unsymmetric `TangentSolver::FactorizeFresh`; never symmetrize pressure tangent.

## RED

Write/register first:

- `NonlinearShellSurfacePressure.AssemblesFollowerForceFromCurrentTrialGeometry`
- `NonlinearShellSurfacePressure.FormsResidualAndTangentWithApprovedExternalSigns`
- `NonlinearShellSurfacePressure.AppliesIncrementFactorExactlyOnce`
- `NonlinearShellSurfacePressure.UsesFullUnsymmetricTangentSolverPath`
- `NonlinearShellSurfacePressure.ConvergesOpenPatchAndPreservesAntisymmetricEvidence`
- `NonlinearShellSurfacePressure.SatisfiesAcceptedFreeResidualAndFactorOneGlobalBalance`
- `NonlinearShellSurfacePressure.IsObjectiveUnderRigidMotionAndTracksCurrentArea`
- `NonlinearShellSurfacePressure.ReducesSerialAndParallelContributionsDeterministically`
- `NonlinearShellSurfacePressure.InvalidTrialRollsBackCommittedFrameAndFinalOutput`
- `NonlinearShellSurfacePressure.WritesSchemaOneExternalInternalResidualReactionAndEquilibrium`
- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingNonlinearBehavior`

Run before production edits:

```powershell
cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
  "-DFESA_GTEST_SOURCE_DIR=C:/git/googletest" `
  "-DMKL_DIR=C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl" `
  "-DTBB_DIR=C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb" `
  "-DHDF5_DIR=C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
cmake --build .harness/build --config Debug --target fesa_unit_tests fesa_integration_tests
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(NonlinearShellSurfacePressure|ShellSurfacePressureApplication)\."
```

Expected RED: current nonlinear procedure includes fixed CLOAD only, so follower force/tangent, objectivity, sign, convergence or balance tests fail. Record command, exit, duration and tail. Unexpected pass is evidence-gap; unrelated failure is regression.

## Minimal GREEN

- At every Newton trial call `AssembleSurfacePressure` with current full generalized coordinates, exact current increment `load_factor` and `kCurrent`.
- Checked-finite add fixed and pressure force/tangent in stable order. Apply source pressure magnitude and load factor exactly once.
- Keep pressure kinematics translation-only; rotation force and tangent blocks stay zero. Retain generally nonsymmetric external tangent and existing `MklPardisoTangentSolver` full CSR `mtype=11` path.
- Form residual and tangent with approved signs in full space before constrained/free extraction. Internal/external residual and tangent must be from the same trial.
- Complete and validate candidate kinematics, force/tangent, residual, equilibrium and convergence before `CommitAcceptedFrame`. Invalid geometry/nonfinite/factorization/solve failures must not append frames or replace final HDF5.
- Preserve existing force/moment convergence channels and thresholds; do not add line search/arc length or alter factor sequence.
- Preserve schema `1` and existing generalized internal/external/residual/reaction/global equilibrium datasets. Add no pressure dataset/version/metadata.

## VERIFY and Acceptance Criteria

Use `.harness/config.json` first if present; otherwise:

```powershell
cmake --build .harness/build --config Debug --target fesa_unit_tests fesa_integration_tests
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(NonlinearShellSurfacePressure|ShellSurfacePressureApplication)\."
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(NonlinearStaticProcedure|NonlinearStaticControl|TangentSolver|NonlinearHdf5ResultsWriter|NonlinearStaticReference)\."
ctest --test-dir .harness/build -C Debug --show-only=json-v1
```

위 targeted build, focused feature/regression tests와 nonzero discovery evidence를 기록한 뒤 Step status/summary를 갱신하고 agent turn을 종료한다. Implementation Agent는 target 없는 whole-project build 또는 unfiltered full CTest를 실행하지 않는다. Automatic Stop hook이 exactly one whole-project MSVC x64 Debug build/full CTest를 수행한다.

Acceptance: local FD `<=1e-8`; objectivity/current-area normalized error `<=1e-12`; factor-one global force/moment balance `<=1e-8`; existing free force/moment residual nonzero-scale relative `<=1e-2`, zero-scale absolute `<=1e-3`; exact zero-scale rules; schema-1 unique factor-one frame projections exact; serial/parallel order exact; invalid trial rollback exact; focused tests pass with nonzero discovery and no warning/runtime staging failure; automatic Stop's exactly one whole-project MSVC x64 Debug build/unfiltered CTest passes.

## 불변식, 실패 처리와 증거

- Candidate-before-commit and same-trial internal/external data are mandatory.
- Failure records deterministic last-completed Newton stage and pressure source identity but publishes no invalid state/output.
- Record RED/GREEN/VERIFY commands, exits, durations/tails, load factor, force/tangent signs and nonsymmetry, solver spy events, iteration count, residual/balance metrics, HDF5 inventory and rollback snapshots.
- Failure classification: `configure | compile | link | test | harness | environment | upstream-contract | regression | evidence-gap`.

Trace: `FESA-REQ-SHELL-PRESSURE-008`–`013`, `016`–`019`, `021`; io §§6–7, 9–10; formulation §§9–14; numerical-review follower/tangent/objectivity/open-patch/balance checks.

## 금지사항

- Do not add line search, arc length, new procedure, convergence threshold changes, PARDISO redesign or HDF5 fields.
- Do not alter Step 3 force/tangent math or Step 4 linear path except a test-proven defect returned to the owning Step through Coordinator.
- Do not modify upstream docs, tolerance/reference artifacts or run Abaqus.
- Do not create output JSON, invoke Executor, advance Step 6, commit or push.