docs: add modular refactoring implementation plan

2026-08-16 02:49:35 +09:00
parent 1e5758f3e4
commit 2ab2e0c641
28 changed files with 2876 additions and 1 deletions
@@ -0,0 +1,163 @@
+# 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를 수동 실행하지 마라.