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

# Step 6: compare-pressure-reference

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

이 Step's single responsibility is to add deterministic comparison support between FESA schema-1 factor-one HDF5 and the exact stored shell-pressure displacement CSV using the unchanged common tolerance. It does not generate reference data and does not write final Gate 6 reports; Step 7 owns closure reports.

Complete RED, expected failure, minimal GREEN and focused VERIFY here, then end so automatic Stop owns exactly one whole-project full verification. Update only Step 6's status and one-line Codex-owned payload. Executor owns all timestamps, commits, retry/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/TOLERANCE.md`
- `docs/shell-surface-pressure-load/requirements.md`
- `docs/shell-surface-pressure-load/numerical-review.md` §§6.2–6.3
- `docs/shell-surface-pressure-load/reference-model.md`
- `docs/shell-surface-pressure-load/io.md` §8
- `docs/shell-surface-pressure-load/implementation-plan.md`
- All prior implemented/test files from Steps 1–5, especially `tests/integration/analysis/shell_surface_pressure_nonlinear_test.cpp`
- `tests/reference/reference_tolerance_policy.h`
- `tests/reference/reference_tolerance_policy.cpp`
- `tests/reference/reference_tolerance_policy_test.cpp`
- `tests/reference/nonlinear_static_reference_comparison.h`
- `tests/reference/nonlinear_static_reference_comparison.cpp`
- `tests/reference/nonlinear_static_reference_cases_test.cpp`
- `tests/reference/mitc4_reference_comparison.h`
- `tests/reference/mitc4_reference_comparison.cpp`
- `tests/reference/mitc4_reference_cases_test.cpp`
- `tests/CMakeLists.txt`
- Read-only exact artifacts listed below

## Exact read-only artifact contract

- Required input: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure.inp`, 56,665 bytes, SHA-256 `53718ccc9b41c23fcc1b509a51d66f1347e87aca43a74f1d6cec4d2085f4b90e`.
- Required comparison CSV: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure displacements.csv`, 111,182 bytes, SHA-256 `2fe53f98eac9f04779100721c3edf8049eb1dbfe733ebcbd819aeeed03b81198`.
- Optional review-only reaction CSV: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure reactions.csv`, never verdict-changing.
- Excluded stress CSV: `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure stresses.csv`, no comparison family.

Never rename, rewrite, normalize, repair, regenerate or reorder any artifact. Never run Abaqus or another reference solver. Run FESA only on a byte-identical copy under `.harness/build/reference/shell-surface-pressure-load/`.

## 소유 파일과 interface boundary

- Create test first: `tests/reference/shell_surface_pressure_reference_test.cpp`
- Modify: `tests/reference/nonlinear_static_reference_comparison.h`
- Modify: `tests/reference/nonlinear_static_reference_comparison.cpp`
- Modify: `tests/CMakeLists.txt`

Preserve existing public operations and extend their per-case value contract minimally:

```cpp
Result<std::vector<ArtifactSnapshot>> ArtifactCheck(
    const NonlinearReferenceCase& reference_case);
Result<std::filesystem::path> CopyInputToExecutionDirectory(
    const NonlinearReferenceCase& reference_case);
Result<GeneratedRunArtifacts> RunFesaApplicationOnCopiedInput(
    const NonlinearReferenceCase& reference_case,
    const std::filesystem::path& copied_input_path);
Result<NonlinearReferenceComparisonReport> CompareHdf5ToReferenceCsv(
    const NonlinearReferenceCase& reference_case,
    const std::filesystem::path& hdf5_results_path);
NonlinearReferenceClassification ClassifyReferenceComparison(
    const NonlinearReferenceComparisonReport& report);
```

Represent required input/displacement, optional reaction and excluded stress disposition as explicit per-case value fields. Do not change `reference_tolerance_policy.*`.

## RED

Write/register first:

- `ShellSurfacePressureReference.AuditsExactRequiredArtifactsAndIgnoresOptionalReviewArtifacts`
- `ShellSurfacePressureReference.SelectsUniqueSchemaOneFactorOneAcceptedFrame`
- `ShellSurfacePressureReference.Projects729WideRowsTo2187LogicalRowsPerFamily`
- `ShellSurfacePressureReference.MatchesByInstanceNodeLabelAndComponentNotRowOrder`
- `ShellSurfacePressureReference.RejectsSchemaIdentityCardinalityMissingExtraDuplicateAndNonfiniteBeforeTolerance`
- `ShellSurfacePressureReference.ClassifiesTranslationBlockingAndRotationWarningOnly`
- `ShellSurfacePressureReference.ExcludesReactionAndStressFamiliesFromVerdict`
- `ShellSurfacePressureReference.UsesUnchangedCommonScaleNearZeroRelativeAndRmsPolicy`
- `ShellSurfacePressureReference.WritesDeterministicComparisonReport`

Run before comparator 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_reference_tests
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^ShellSurfacePressureReference\."
```

Expected RED: current nonlinear registry has no pressure case/disposition and assumes a legacy artifact portfolio, so the exact two-required-file contract, schema/frame projection or 729/2187 cardinality fails. Record command, exit, duration and tail. Unexpected pass is evidence-gap; unrelated failure is regression.

## Minimal GREEN

- Snapshot exact required artifacts before run, byte-copy only the input into the build tree, and run FESA application only.
- Require HDF5 schema `1`, exact `Step-1`, a unique accepted frame with `load_factor==1`/`is_factor_one`, `/model/nodes`, and existing nodal displacement.
- Join HDF5 nodes and CSV by `(instance_name="Part-1-1", source node label, component)`, never row order/internal index. Expand 729 wide rows to 2,187 `U1/U2/U3` logical rows and 2,187 `UR1/UR2/UR3` rows.
- Reject schema/frame/identity/cardinality, missing, extra, duplicate and nonfinite rows before tolerance.
- After prechecks only, call unchanged `EvaluateReferenceTolerance`: `S=max(abs(reference))`; near-zero band `0.01*S`; near-zero absolute row error `<=0.01*S`; otherwise relative `<=0.05`; `RMS(error)/S<=0.01`; zero-scale requires FESA exact zero.
- Translation is blocking; rotation is warning-only. Reaction creates no numerical comparator family and is review-only; stress is excluded.
- Produce deterministic row, family metric, warning and classification order. HDF5-derived CSV, if any, is debug-only and not official output.

## VERIFY and Acceptance Criteria

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

```powershell
cmake --build .harness/build --config Debug --target fesa_reference_tests
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^ShellSurfacePressureReference\."
ctest --test-dir .harness/build -C Debug --output-on-failure -R "^(NonlinearStaticReference|ReferenceTolerancePolicy|Mitc4Reference)\."
ctest --test-dir .harness/build -C Debug --show-only=json-v1
```

위 targeted build, focused pressure/reference regressions와 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: exact input/CSV size+hash unchanged before/after; 729 unique node keys; 2,187 rows in each U/UR family; all prechecks precede tolerance; common policy unchanged; U blocking and UR warning-only; reaction/stress dispositions exact; deterministic report; focused tests pass with nonzero discovery and no new warning/runtime staging failure; automatic Stop's exactly one whole-project MSVC x64 Debug build/unfiltered CTest passes.

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

- Artifact/precheck failure returns a failed classification without tolerance evaluation or artifact mutation.
- Copied input/generated HDF5/log live only under build tree.
- Record pre/post snapshots, copy/generated paths, selected frame identity, cardinalities, family scale/row/RMS/worst row, warnings, classification and RED/GREEN/VERIFY command evidence.
- Failure classification: `configure | compile | link | test | reference-comparison | artifact | harness | environment | upstream-contract | regression | evidence-gap`.

Trace: `FESA-REQ-SHELL-PRESSURE-017`–`019`, `021`–`024`; io §8; reference-model §§3–8; numerical-review external acceptance.

## 금지사항

- Do not generate/edit/rename reference files, change tolerance, promote reaction/stress, add metadata requirements or run Abaqus.
- Do not modify solver production unless failure is returned through Coordinator to the owning implementation Step.
- Do not write final reports yet, create output JSON, invoke Executor, advance Step 7, commit or push.