# Step 13: Shell Reference Comparison

## 담당 역할과 필수 스킬

- 담당 역할: `implementation-agent`
- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
- 이 Step은 test-only reference module을 소유하며 solver production module을 소유하지 않는다.

## 읽어야 할 파일

- `/.agents/skills/harness/SKILL.md`, `/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`
- `/AGENTS.md`, `/docs/PRD.md`, `/docs/ARCHITECTURE.md`, `/docs/ADR.md`
- `/docs/HARNESS.md`, `/docs/HARNESS_WORKFLOW.md`, `/.codex/hooks.json`
- `/docs/linear-static-mitc4-shell/implementation-plan.md`
- `/docs/linear-static-mitc4-shell/requirements.md` Requirements 053/058-072
- `/docs/linear-static-mitc4-shell/research.md`
- `/docs/linear-static-mitc4-shell/formulation.md`
- `/docs/linear-static-mitc4-shell/numerical-review.md`
- `/docs/linear-static-mitc4-shell/io.md` Section 7
- `/docs/linear-static-mitc4-shell/reference-model.md`
- phase indexes, `step13.md`, completed Steps 11/12 paths and summaries
- `/tests/reference/reference_comparison.hpp`와 cpp/test는 B33 identity/report precedent
- Candidate new `/tests/reference/mitc4_reference_comparison.hpp`
- Candidate new `/tests/reference/mitc4_reference_comparison.cpp`
- Candidate new `/tests/reference/mitc4_reference_comparison_test.cpp`
- Candidate new `/tests/reference/mitc4_reference_cases_test.cpp`
- `/tests/CMakeLists.txt`
- Read-only:
  `/reference/shell/shell.inp`,
  `/reference/shell/shell displacements.csv`

## 작업

1. 기존 `MITC4-REF-003`을 먼저 고정 절대 tolerance boundary test로 바꾸고 현재
   scale-dependent comparator에서 예상대로 실패하는 RED를 확인한다. 나머지
   `MITC4-REF-001..006`, `MITC4-E2E-S4-001/002` coverage는 유지한다.
2. Test-only comparator는 각 case의 exact input/displacement CSV와 FESA HDF5만 요구한다.
   `Part Instance Name`와 `Node Label`을 HDF5 node identity에 match하고 CSV
   `U-U1..U-U3, UR-UR1..UR-UR3`를 displacement columns 0..5에 match한다.
3. Header/schema/row set/missing/extra/duplicate/nonfinite/source identity를 numeric
   comparison 전에 fail한다.
4. 모든 matched U/UR row에 고정 절대 tolerance `1.0e-5`를 scale/clamp/row denominator
   없이 적용한다. Reference scale은 report diagnostic으로만 남길 수 있다.
   U1/U2/U3만 blocking이고 UR1/UR2/UR3 exceedance는 deterministic warning-only다.
5. 모든 row decision, max absolute, normalized, RMS, vector norm, worst source row/component를
   deterministic report/JSON에 남긴다.
6. S4 HDF5가 source type `S4`와 `FESA-MITC4` full-integration rule을 기록하는지
   검증한다. S4R common-path/source-metadata coverage는 완료된 Steps 1/7/11 tests가
   소유하며 이 Step은 S4R Abaqus artifact를 소비하지 않는다.
7. Declared case가 solver production defect를 드러내면 current Step을 중단하고
   Correction/Coordinator에 owning prior module로 handoff한다. 이 Step에서 그 production
   file을 수정하지 않는다.

## Acceptance Criteria

먼저 exact expected hashes를 검증한다.

```powershell
$expectedReferenceHashes=[ordered]@{
  "reference/shell/shell.inp"="4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF"
  "reference/shell/shell displacements.csv"="C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B"
}
foreach($p in $expectedReferenceHashes.Keys){
  if((Get-FileHash -Algorithm SHA256 -LiteralPath $p).Hash -ne $expectedReferenceHashes[$p]){
    throw "Reference artifact changed: $p"
  }
}
$requiredBuildPaths=@("C:/git/googletest","C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl","C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb","C:/Program Files/HDF_Group/HDF5/2.1.1/cmake")
foreach($p in $requiredBuildPaths){if(-not(Test-Path -LiteralPath $p)){throw "Missing $p"}}
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 -R "Mitc4ReferenceComparison|Mitc4S4Reference" --output-on-failure
```

기존 mixed-tolerance 구현에 대한 fixed-boundary RED를 확인하고 test-only minimal GREEN. 이후:

```powershell
cmake --build .harness/build --config Debug --target fesa_reference_tests
ctest --test-dir .harness/build -C Debug -R "Mitc4ReferenceComparison|Mitc4S4Reference" --output-on-failure
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
foreach($p in $expectedReferenceHashes.Keys){
  if((Get-FileHash -Algorithm SHA256 -LiteralPath $p).Hash -ne $expectedReferenceHashes[$p]){
    throw "Reference artifact changed: $p"
  }
}
git diff --check
```

## 검증 및 상태 갱신

RED/comparator/E2E/full/hash evidence를 기록하고 current Step 상태 payload만 갱신한다.

## 금지사항

- Abaqus/reference solver를 실행하거나 reference 파일을 생성·수정·rename·repair하지 마라.
- README, metadata.json, provenance, Abaqus version을 gate로 만들지 마라.
- UR warning을 blocking으로 바꾸거나 고정 `1.0e-5`를 scale/calibration/clamp로 대체하지 마라.
- B33 comparator 또는 B33 tolerance를 수정하지 마라.
- Reaction/stress equality gate나 Abaqus formulation equivalence를 추가하지 마라.
- Solver production file을 수정하거나 직접 commit/hook 실행을 하지 마라.