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,99 @@
+# Step 3: Foundation Google Style
+
+## 담당 역할과 필수 스킬
+
+- 담당 역할: `implementation-agent`
+- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
+- 이 Step만 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`로 수행한다.
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/CODINGSTYLE.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
+- `/include/fesa/core/diagnostic.hpp`
+- `/include/fesa/core/source_identity.hpp`
+- `/include/fesa/core/status.hpp`
+- `/include/fesa/math/vector.hpp`
+- `/include/fesa/math/matrix.hpp`
+- `/include/fesa/math/sparse_matrix.hpp`
+- `/include/fesa/solvers/linear/linear_solver.hpp`
+- `/include/fesa/solvers/linear/mkl_pardiso_solver.hpp`
+- `/include/fesa/build_info.hpp`
+- `/src/fesa/core/diagnostic.cpp`, `/src/fesa/core/status.cpp`
+- `/src/fesa/math/vector.cpp`, `/src/fesa/math/matrix.cpp`,
+  `/src/fesa/math/sparse_matrix.cpp`
+- `/src/fesa/solvers/linear/mkl_pardiso_solver.cpp`, `/src/fesa/build_info.cpp`
+- `/tests/unit/core/diagnostic_test.cpp`, `/tests/unit/core/source_identity_test.cpp`,
+  `/tests/unit/core/status_test.cpp`
+- `/tests/unit/math/vector_test.cpp`, `/tests/unit/math/matrix_test.cpp`,
+  `/tests/unit/math/sparse_matrix_test.cpp`
+- `/tests/unit/solvers/linear/linear_solver_test.cpp`,
+  `/tests/unit/solvers/linear/mkl_pardiso_solver_test.cpp`
+- `/tests/unit/build_info_test.cpp`
+- `/src/fesa/CMakeLists.txt`, `/tests/CMakeLists.txt`
+- `/phases/cpp-object-oriented-modular-refactoring/index.json`
+- `/phases/cpp-object-oriented-modular-refactoring/step3.md`
+
+## 작업
+
+Requirement `R-STYLE-001`의 foundation slice와 `R-DOC-001`을 구현한다. 동작 또는
+수치식은 변경하지 않는다.
+
+1. Focused tests의 include를 `.h`로, 모든 function/accessor call을 PascalCase로 먼저
+   변경하고 missing header/member compile failure를 RED로 기록한다.
+2. 다음 production headers를 같은 basename의 `.h`로 이동하고 full-path include guard를
+   사용한다: core headers, `vector`, `matrix`, `sparse_matrix`, `linear_solver`,
+   `mkl_pardiso_solver`, `build_info`.
+3. 이 slice가 소유하는 public/protected function과 production internal function 이름을
+   PascalCase로 바꾼다. Parameters/local variables는 snake_case, class members는 trailing
+   underscore, enum values/constants는 `kPascalCase`로 바꾼다.
+4. Public/protected declarations에 `@brief`와 필요한 ownership/failure/backend contract를
+   Doxygen으로 기록한다. Tests에는 Doxygen를 추가하지 않는다.
+5. 모든 repository consumer include/callsite를 기계적으로 갱신하되 다른 모듈의 함수
+   정의나 책임은 바꾸지 않는다.
+6. Matrix/Vector 연산 순서, MKL calls, Status category, diagnostic text는 보존한다.
+
+## Acceptance Criteria
+
+RED 후 GREEN focused/full verification:
+
+```powershell
+cmake -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_unit_tests
+ctest --test-dir .harness/build -C Debug `
+  -R "DenseMath|SparseAssembly|Status|Diagnostic|LinearSolver|MklPardiso|BuildInfo" `
+  --output-on-failure
+$files = @(
+  (rg --files include/fesa/core include/fesa/math include/fesa/solvers/linear `
+    -g "*.h"),
+  "include/fesa/build_info.h",
+  (rg --files src/fesa/core src/fesa/math src/fesa/solvers/linear -g "*.cpp"),
+  "src/fesa/build_info.cpp",
+  (rg --files tests/unit/core tests/unit/math tests/unit/solvers/linear -g "*.cpp"),
+  "tests/unit/build_info_test.cpp"
+)
+& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror $files
+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
+```
+
+## 검증 및 상태 갱신
+
+- RED compile error, focused GREEN, formatting, full CTest를 summary에 남긴다.
+- 성공 시 현재 Step만 `completed`; 반복 compile failure는 `error`로 기록한다.
+- timestamp, retry, commit, advancement는 Executor 소유다.
+
+## 금지사항
+
+- `Vector3`나 BLAS adapter를 추가하지 마라. 이유: Step 7과 10의 semantic work다.
+- 수치 expression/reduction 순서를 바꾸지 마라. 이유: style-only review unit이다.
+- Test에 Doxygen를 추가하지 마라. 이유: 승인 문서화 범위는 production뿐이다.
+- 직접 commit하거나 hook script를 수동 실행하지 마라.