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

# Step 4: integrate-linear-shell-pressure

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

이 Step의 single responsibility는 Step 3 local evaluator를 deterministic full-space pressure assembler와 linear-static reference-configuration path에 연결하고 existing schema-0/CLI/reaction/equilibrium behavior를 검증하는 것이다. Nonlinear follower procedure는 Step 5 범위다.

Complete test-first RED, expected failure, minimal GREEN, focused and full VERIFY in this Step. Update only Step 4's selected status and one-line Codex-owned payload. Executor owns branch, retry, timestamps, commit, advancement, top-level phase 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, 11–14
- `docs/shell-surface-pressure-load/numerical-review.md` §6
- `docs/shell-surface-pressure-load/io.md` §§6–7, 9–10
- `docs/shell-surface-pressure-load/implementation-plan.md`
- Prior semantic 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 outputs: `include/fesa/loads/shell_surface_pressure.h`, `src/fesa/loads/shell_surface_pressure.cpp`, `tests/unit/loads/shell_surface_pressure_test.cpp`
- `include/fesa/assembly/load_assembler.h`
- `src/fesa/assembly/load_assembler.cpp`
- `include/fesa/assembly/sparse_assembler.h`
- `src/fesa/assembly/sparse_assembler.cpp`
- `include/fesa/assembly/parallel_for.h`
- `src/fesa/assembly/parallel_for.cpp`
- `include/fesa/fem/dof_manager.h`
- `src/fesa/fem/dof_manager.cpp`
- `src/fesa/analysis/linear_static_procedure.cpp`
- `include/fesa/analysis/analysis_state.h`
- `src/fesa/analysis/analysis_state.cpp`
- `include/fesa/results/result_recovery.h`
- `src/fesa/results/result_recovery.cpp`
- `src/fesa/results/global_equilibrium_recovery.h`
- `src/fesa/results/global_equilibrium_recovery.cpp`
- `include/fesa/io/hdf5/hdf5_results_writer.h`
- `src/fesa/io/hdf5/hdf5_results_writer.cpp`
- `src/fesa/io/hdf5/hdf5_self_check.h`
- `src/fesa/io/hdf5/hdf5_self_check.cpp`
- `src/fesa/app/fesa_application.cpp`
- `tests/unit/assembly/load_assembler_test.cpp`
- `tests/unit/assembly/sparse_assembler_test.cpp`
- `tests/integration/analysis/linear_static_analysis_test.cpp`
- `tests/integration/app/fesa_application_test.cpp`
- `tests/unit/io/hdf5/hdf5_results_writer_test.cpp`
- `src/fesa/CMakeLists.txt`
- `tests/CMakeLists.txt`

## 소유 파일과 인터페이스

- Create test first: `tests/unit/assembly/surface_pressure_assembler_test.cpp`
- Create test first: `tests/integration/analysis/shell_surface_pressure_linear_test.cpp`
- Create test first: `tests/integration/app/shell_surface_pressure_application_test.cpp`
- Create: `include/fesa/assembly/surface_pressure_assembler.h`
- Create: `src/fesa/assembly/surface_pressure_assembler.cpp`
- Modify: `src/fesa/analysis/linear_static_procedure.cpp`
- Modify/Test assertions only: `tests/unit/io/hdf5/hdf5_results_writer_test.cpp`
- Modify: `src/fesa/CMakeLists.txt`
- Modify: `tests/CMakeLists.txt`

HDF5 production writer and `fesa_application.cpp` are expected no-change verification targets. Modify them only if a new RED test proves a direct approved-contract gap, and record that evidence and minimal reason.

Assembler contract:

```cpp
struct SurfacePressureAssemblyCandidate {
  Vector full_external_force;
  SparseMatrix full_external_tangent;
  std::vector<Diagnostic> diagnostics;
};

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

The input vector is stable full-DOF `[u1,u2,u3,phi1,phi2,phi3]`. Produce local candidates in `(load_ordinal, facet_ordinal, instance declaration ordinal, element label, local row[,column])`, use worker-local buffers and reduce in that exact serial order. Workers never update global vector/CSR directly.

## RED

Write/register first:

- `SurfacePressureAssembly.AssemblesFullDofsInPressureFacetAndRecordOrder`
- `SurfacePressureAssembly.AddsRepeatedRecordsAndAppliesUnitFactorExactlyOnce`
- `SurfacePressureAssembly.IsBitwiseStableForSerialAndParallelLocalEvaluation`
- `LinearShellSurfacePressure.UsesReferenceNormalAndAreaAfterPrescribedDisplacement`
- `LinearShellSurfacePressure.AssemblesBeforeProjectionAndIncludesConstrainedReaction`
- `LinearShellSurfacePressure.SatisfiesFreeResidualGlobalResultantAndMoment`
- `LinearShellSurfacePressure.PreservesS4S4rMeshAndCyclicOrderInvariance`
- `LinearShellSurfacePressure.WritesSchemaZeroWithoutPressureDataset`
- `ShellSurfacePressureApplication.LinearFailurePreservesExistingFinalAndNoCandidate`
- `ShellSurfacePressureApplication.InputWithoutPressureRetainsExistingLinearBehavior`

Run before production implementation:

```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 "^(SurfacePressureAssembly|LinearShellSurfacePressure|ShellSurfacePressureApplication)\."
```

Expected RED: assembler compile/link failure, or linear procedure assembles only CLOAD so pressure resultant/reaction remains zero and pressure CLI assertions fail. Record command, exit, duration and output tail. Unexpected pass is evidence-gap; unrelated failure is regression.

## Minimal GREEN

- Create evaluator inputs from immutable Domain source identity and stable DofManager scatter. Evaluate every `(load_ordinal, facet_ordinal)`, including zero pressure/factor geometry validation.
- Keep worker-local force/tangent contributions. Validate all candidates before fixed serial reduction; no global concurrent writes.
- In `LinearStaticProcedureExecutor`, preserve element stiffness assembly, `Kff/Kfc` partition and `Kff` factorization-before-load order.
- Assemble existing CLOAD and reference pressure separately, checked-finite add their full-space forces, and assign `AnalysisState::ExternalForce()` exactly once before free/constrained projection.
- Call pressure assembler with load factor exactly `1.0`, reference configuration and a full generalized-coordinate vector of the required size. Linear pressure tangent is exact zero and does not change stiffness.
- Preserve `EffectiveFreeRhs(Ff-Kfc*dc)`, valid `0x0 Kff`, full displacement reconstruction and `K*d-F` recovery. Constrained residual is reaction; free residual is equilibrium evidence.
- Preserve current schema version `0`, mandatory result inventory, CLI sibling naming and atomic candidate finalization. Add no surface/load/pressure dataset or 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 "^(SurfacePressureAssembly|LinearShellSurfacePressure|ShellSurfacePressureApplication)\."
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(LoadAssembly|SparseAssembly|LinearStaticCli|Mitc4ShellCli|Hdf5ResultsWriter)\."
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Acceptance:

- normalized analytical force/moment/reaction/mesh/order errors `<=1e-12`;
- global force and moment balance `<=1e-8` and approved existing free-residual gates;
- serial/parallel external vectors, diagnostics and row order exact;
- schema `0`, existing mandatory datasets only, no pressure-specific path;
- failed pressure candidate leaves prior final bytes unchanged or no misleading final;
- inputs without pressure retain current results;
- nonzero CTest inventory, full pass, no new MSVC warning and runtime staging succeeds.

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

- Full-space completion precedes projection; source/internal/equation IDs remain distinct.
- Load factor is applied exactly once; repeated pressure records remain additive.
- Any local/nonfinite/assembly/recovery failure returns before state/result publication.
- Record RED/GREEN/VERIFY commands, exits, durations/tails, contribution order, external/reaction/residual/resultant values, schema inventory and final-file snapshots.
- Failure classification: `configure | compile | link | test | harness | environment | upstream-contract | regression | evidence-gap`.

Trace: `FESA-REQ-SHELL-PRESSURE-005`–`007`, `010`–`013`, `016`–`020`; io §§6–7, 9–10; formulation §§9, 11–14; numerical-review linear/resultant/balance checks.

## 금지사항

- Do not implement nonlinear follower procedure, change the linear solver backend, HDF5 schema or output inventory.
- Do not refactor existing load hierarchy beyond the new pressure assembler or expose MKL/TBB/HDF5 in public core.
- Do not modify upstream docs, tolerance/reference artifacts or Abaqus files.
- Do not run Abaqus, create output JSON, invoke Executor, advance Step 5, commit or push.