FESADev/phases/cpp-object-oriented-modular-refactoring/step24.md

# Step 24: Final Quality and Reference Gate

## 담당 역할과 필수 스킬

- 담당 역할: `implementation-agent`
- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`, `superpowers:verification-before-completion`
- This is the final Implementation-owned verification Step. Execute
  `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` in that literal order.

## 읽어야 할 파일

- `/.agents/skills/harness/SKILL.md`
- `/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`
- `/AGENTS.md`
- `/docs/CODINGSTYLE.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
- `/docs/linear-static-3d-euler-beam/requirements.md`
- `/docs/linear-static-3d-euler-beam/reference-model.md`
- `/docs/linear-static-3d-euler-beam/io.md`
- `/docs/linear-static-mitc4-shell/requirements.md`
- `/docs/linear-static-mitc4-shell/reference-model.md`
- `/docs/linear-static-mitc4-shell/io.md`
- `/tests/reference/b33_reference_comparison_test.cpp`
- `/tests/reference/mitc4_reference_cases_test.cpp`
- all Step 0–23 summaries and changed files
- `/phases/cpp-object-oriented-modular-refactoring/index.json`
- `/phases/cpp-object-oriented-modular-refactoring/step24.md`

## 작업

Requirements `R-PRESERVE-001`, `R-STYLE-001`, `R-DOC-001`, `R-SCOPE-001` and every
traceability row를 최종 검증한다. No production behavior is added in this Step.

1. Review all prior diffs against the approved design. Remove only orphaned compatibility includes,
   declarations or helpers created by this phase; do not clean unrelated pre-existing code.
2. Verify every production/test header under `include`, `src`, `tests` uses `.h`; every production
   public/protected API follows PascalCase and production Doxygen policy; tests have no imposed
   Doxygen boilerplate.
3. Run clang-format on every tracked C++ file in dry-run error mode and the selected clang-tidy
   C++17 public-header check. Do not run Doxygen; generation is deferred by user decision.
4. Fresh configure and full MSVC x64 Debug `/W4 /WX` build/CTest.
5. ARTIFACT CHECK before comparison:
   - Assert exact B33 input and three CSV files exist under `/reference/cantilever beam/`.
   - Assert exact MITC4 S4 input and displacement CSV exist under `/reference/shell/`.
   - Snapshot/diff reference tree against baseline commit `1e5758f`.
6. COMPARE by running only the approved B33 and MITC4 S4 reference suites. Confirm generated:
   - `.harness/build/reference/cantilever-beam-b33/results.h5`
   - `.harness/build/reference/mitc4-shell-s4-comparison/results.h5`
7. CLASSIFY missing/extra/duplicate/nonfinite/tolerance failure before reporting. B33 retains its
   existing component-scale policy. MITC4 U1/U2/U3 use fixed `1.0e-5`; UR1/UR2/UR3 remain warning-only.
8. REPORT by creating/updating:
   - `/docs/cpp-object-oriented-modular-refactoring/implementation-report.md`
   - `/docs/cpp-object-oriented-modular-refactoring/build-test.md`
   - `/docs/cpp-object-oriented-modular-refactoring/reference-comparison.md`
9. `implementation-report.md` records each Step RED/GREEN/VERIFY command and result summary.
10. `build-test.md` records metadata with `owner_agent: implementation-agent`, environment,
    command/exit code/duration/output tail, test inventory, classification, no-change assertion,
    handoff and open issues.
11. `reference-comparison.md` records exact artifact inventory, generated HDF5 paths, HDF5-to-CSV
    identity/component projection, row prechecks, approved tolerances, per-row decisions and only
    contract-applicable metrics, classification and no-change assertion.

## Acceptance Criteria

Style and policy:

```powershell
uv run --with pytest python -m pytest -v -rs
& "C:/Program Files/LLVM/bin/clang-format.exe" --version
& "C:/Program Files/LLVM/bin/clang-tidy.exe" --version
& "C:/Program Files/LLVM/bin/clang-tidy.exe" --verify-config
$cppFiles = @(rg --files include src tests -g "*.h" -g "*.cpp")
& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror $cppFiles
$publicHeaders = @(rg --files include/fesa -g "*.h")
foreach ($publicHeader in $publicHeaders) {
  & "C:/Program Files/LLVM/bin/clang-tidy.exe" --config-file=.clang-tidy `
    $publicHeader -- -x c++ -std=c++17 -Iinclude
  if ($LASTEXITCODE -ne 0) {
    throw "clang-tidy failed for $publicHeader"
  }
}
$legacyHeaders = @(rg --files include src tests -g "*.hpp")
if ($legacyHeaders.Count -ne 0) {
  $legacyHeaders
  throw "Legacy .hpp headers remain"
}
```

Fresh MSVC build and full tests:

```powershell
$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 ($requiredBuildPath in $requiredBuildPaths) {
  if (-not (Test-Path -LiteralPath $requiredBuildPath)) {
    throw "Missing $requiredBuildPath"
  }
}
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_tests
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

ARTIFACT CHECK, COMPARE and post-check:

```powershell
$declaredArtifacts = @(
  "reference/cantilever beam/cantilever beam.inp",
  "reference/cantilever beam/cantilever beam displacements.csv",
  "reference/cantilever beam/cantilever beam elemental forces.csv",
  "reference/cantilever beam/cantilever beam reactions.csv",
  "reference/shell/shell.inp",
  "reference/shell/shell displacements.csv"
)
foreach ($declaredArtifact in $declaredArtifacts) {
  if (-not (Test-Path -LiteralPath $declaredArtifact -PathType Leaf)) {
    throw "Missing declared artifact: $declaredArtifact"
  }
}
git diff --exit-code 1e5758f -- reference
ctest --test-dir .harness/build -C Debug `
  -R "B33ReferenceComparison|Mitc4S4Reference" --output-on-failure
$generatedResults = @(
  ".harness/build/reference/cantilever-beam-b33/results.h5",
  ".harness/build/reference/mitc4-shell-s4-comparison/results.h5"
)
foreach ($generatedResult in $generatedResults) {
  if (-not (Test-Path -LiteralPath $generatedResult -PathType Leaf)) {
    throw "Missing generated solver result: $generatedResult"
  }
}
git diff --exit-code 1e5758f -- reference
git diff --check
```

## 검증 및 상태 갱신

- Do not mark complete until every command and report section has observed evidence.
- Success summary names style gate, full discovered test count, both generated results, blocking
  comparison verdicts, reference no-change assertion and report paths.
- Implementation-owned compile/test/comparison failure is `error` with classification and exact
  failed command. Missing tool or declared artifact is `blocked` with exact path.
- On success update only current Step to `completed`; final timestamps, commit and top-level phase
  completion are Executor-owned.

## 금지사항

- Doxygen executable을 실행하거나 generated docs를 commit하지 마라. 이유: 사용자 결정으로 연기됐다.
- Reference artifact, input, CSV, tolerance or comparator contract를 변경하지 마라.
- Passing comparison만으로 release or physics readiness를 승인하지 마라.
- Failure를 숨기기 위해 clamp, missing-row ignore, average or tolerance relaxation을 추가하지 마라.
- 직접 commit하거나 hook script를 수동 실행하지 마라.