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

# Step 3: evaluate-shell-pressure-kernel

> 과거 개발 계획이다. 아래 작업·상태·예시는 현재 실행 지시가 아니다.
> 현재 구현과 검증 한계는 [기능 요약](../../docs/shell-surface-pressure-load/README.md)을 따른다.

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

이 Step의 단일 책임은 one four-node shell facet의 reference/current surface-pressure `24x1` external force와 exact `24x24` external tangent를 backend-neutral하게 계산하는 것이다. Parser, full-space assembler, analysis procedure and HDF5 integration은 범위 밖이다. Same Step에서 RED, expected failure, minimal GREEN and focused VERIFY를 수행한 뒤 종료하며, automatic Stop hook이 exactly one whole-project full verification을 소유한다.

Implementation Agent는 Step 3 record의 `status`와 한 줄 `summary`/`error_message`/`blocked_reason`만 기록한다. Executor는 branch, retry, timestamps, commit, advancement, top-level status and output JSON을 소유한다.

## 읽어야 할 파일

- `AGENTS.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `.codex/hooks.json`
- `../../docs/shell-surface-pressure-load/README.md`
- `../../docs/shell-surface-pressure-load/formulation.md` §§6, 9–10, 13–14
- `../../docs/shell-surface-pressure-load/README.md` §§3–6
- `../../docs/shell-surface-pressure-load/README.md` §§4–6, 9
- `../../docs/shell-surface-pressure-load/README.md`
- `include/fesa/model/model_types.h`
- `include/fesa/model/shell_geometry.h`
- `src/fesa/model/shell_geometry.cpp`
- `include/fesa/elements/mitc4_shell.h`
- `src/fesa/elements/mitc4_shell.cpp`
- `include/fesa/elements/nonlinear_mitc4_shell.h`
- `src/fesa/elements/nonlinear_mitc4_shell.cpp`
- `include/fesa/math/vector3.h`
- `include/fesa/math/matrix.h`
- `tests/unit/elements/mitc4_shell_test.cpp`
- `tests/unit/elements/nonlinear_mitc4_shell_test.cpp`
- `tests/unit/elements/nonlinear_mitc4_shell_tangent_test.cpp`
- `src/fesa/CMakeLists.txt`
- `tests/CMakeLists.txt`

Prior-Step files to read: `src/fesa/io/abaqus/surface_definition_mapper.h/.cpp`, `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`, `tests/unit/io/abaqus/shell_surface_pressure_domain_test.cpp`. They define immutable side/magnitude/source identity only; this Step must not revise parser semantics.

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

- Create test first: `tests/unit/loads/shell_surface_pressure_test.cpp`
- Create: `include/fesa/loads/shell_surface_pressure.h`
- Create: `src/fesa/loads/shell_surface_pressure.cpp`
- Modify: `src/fesa/CMakeLists.txt`
- Modify: `tests/CMakeLists.txt`

Implement this semantic interface:

```cpp
enum class SurfacePressureConfiguration { kReference, kCurrent };

struct ShellSurfacePressureInput {
  std::array<Vector3, 4> reference_coordinates;
  std::array<Vector3, 4> translational_displacements;
  ShellSurfaceSide side;
  double pressure_magnitude;
  double load_factor;
  SurfacePressureConfiguration configuration;
  SourceLocation location;
  std::string entity_identity;
};

struct ShellSurfacePressureContribution {
  std::array<double, 24> force;
  std::array<double, 24 * 24> external_tangent;
};

Result<ShellSurfacePressureContribution> EvaluateShellSurfacePressure(
    const ShellSurfacePressureInput& input);
```

The tangent is fixed-node/source-order row-major. Translation DOFs occupy local components 0–2 per node; all rotation force entries and all tangent rows/columns touching components 3–5 are exact zero. No MKL, TBB, HDF5, parser or procedure type may cross this public solver-core boundary.

## RED

Write and register these tests before the new production header/source:

- `ShellSurfacePressureKernel.PartitionsUnityAndIntegratesPlanarResultantAndMoment`
- `ShellSurfacePressureKernel.ReversesExactlyForSposSnegAndNegativeMagnitude`
- `ShellSurfacePressureKernel.UsesReferenceGeometryWithExactZeroLinearTangent`
- `ShellSurfacePressureKernel.UsesCurrentAreaAndNormalForFollowerForce`
- `ShellSurfacePressureKernel.HasExactZeroRotationalForceRowsAndTangentBlocks`
- `ShellSurfacePressureKernel.IsTranslationAndRigidRotationObjective`
- `ShellSurfacePressureKernel.IsCovariantUnderCyclicNodeRelabeling`
- `ShellSurfacePressureKernel.MatchesCenteredFiniteDifferenceForForceAndResidualSigns`
- `ShellSurfacePressureKernel.PreservesGenerallyNonsymmetricFollowerTangent`
- `ShellSurfacePressureKernel.RejectsNonfiniteCollapsedFoldedAndInvertedGeometryAtEveryRequiredPoint`
- `ShellSurfacePressureKernel.ValidatesGeometryEvenForZeroPressureOrFactor`

Run:

과거 도구 실행·출력 지시는 정리했으며, 현재 검증 방법은 기능 요약을 따른다.

Expected RED: compile/link fails because the evaluator declaration/definition is absent. If the header is staged first, physics assertions must fail until implementation exists. Record exact command, exit, duration and tail. Do not use existing MITC4 internal-force code as pressure GREEN. Unexpected pass is evidence-gap; unrelated failure is regression.

## Minimal GREEN

- Use one common `2x2` Gauss rule in fixed order `(-1/sqrt(3),-1/sqrt(3))`, `(+,-)`, `(+,+)`, `(-,+)` and bilinear four-node `N_i`/derivatives.
- Let `s=+1` for SPOS and `s=-1` for SNEG. At each point use the approved area vector and compute `f_i = -lambda*p*s*sum(w*N_i*a)`.
- Reference configuration ignores displacement and returns an exactly zero tangent. Current configuration uses only translations in `x=X+u`.
- Implement the exact current follower derivative
  `K_ext,ij = lambda*p*s*sum(w*N_i*(N_j,xi*[g_eta]_x - N_j,eta*[g_xi]_x))`.
  Test both external-force derivative and residual-sign form. Never symmetrize it.
- Validate finite input/intermediates and the approved mean/corner/Gauss chord-scaled geometry rules with the single dimensionless `tau_J=1e-12`. Validate geometry even if `p==0` or `lambda==0`.
- Do not use `max(1,...)`, absolute floors, zero clamps, connectivity reorder or normal flips.

## VERIFY and Acceptance Criteria

Use 과거 검증 자료(정리됨) first if present; otherwise:

과거 도구 실행·출력 지시는 정리했으며, 현재 검증 방법은 기능 요약을 따른다.

Acceptance:

- shape-function sum error `<=1e-14`;
- normalized resultant, moment, sign, objectivity and covariance errors `<=1e-12`;
- centered FD uses `h=1e-5` and normalized tangent error `<=1e-8`;
- rotation blocks are bitwise/exact zero;
- at least one approved off-diagonal antisymmetric tangent pair is nonzero;
- every invalid geometry/nonfinite case fails without a contribution;
- nonzero CTest inventory, focused feature/regression pass, no new MSVC warning;
- automatic Stop의 exactly one whole-project MSVC x64 Debug build/unfiltered CTest pass.

위 명령과 증거를 기록한 뒤 Step status/summary를 갱신하고 agent turn을 종료한다. Implementation Agent는 target 없는 whole-project build 또는 unfiltered full CTest를 실행하지 않는다. Stop hook이 자동으로 exactly one whole-project build/full CTest를 수행하며 hook entry point를 수동 실행하지 않는다.

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

- Force and tangent use identical geometry and Gauss evaluations.
- Failure returns no contribution and does not mutate caller arrays/state.
- Fixed loop/order yields deterministic values and diagnostics.
- Record RED/GREEN/VERIFY commands, exits, durations/tails, normalized metrics, FD numerator/denominator/h, antisymmetric entries, exact-zero checks and diagnostic identity/location.
- Failure classification: `configure | compile | link | test | harness | environment | upstream-contract | regression | evidence-gap`.

Trace: `FESA-REQ-SHELL-PRESSURE-005`–`009`, `016`, `020`–`021`; formulation §§6, 9–10, 13–14; numerical-review kernel/objectivity/tangent/geometry checks.

## 금지사항

- Do not alter MITC4 internal constitutive/stiffness formulation, add pressure stress recovery, configurable integration or vendor dependencies.
- Do not implement full-space assembly or linear/nonlinear procedure changes; those belong to Steps 4–5.
- Do not modify parser contracts, upstream docs, HDF5, tolerance or reference artifacts.
- Do not run reference solvers, create output JSON, invoke Executor, advance Step 4, commit or push.