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,76 @@
+# Step 1: C++ Style Tooling
+
+## 담당 역할과 필수 스킬
+
+- 담당 역할: `implementation-agent`
+- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
+- 이 Step만 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`로 수행한다.
+
+## 읽어야 할 파일
+
+- `/.agents/skills/harness/SKILL.md`
+- `/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`
+- `/AGENTS.md`
+- `/docs/CODINGSTYLE.md`
+- `/docs/superpowers/specs/2026-08-16-cpp-object-oriented-modular-refactoring-design.md`
+- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
+- `/CMakeLists.txt`
+- `/.gitignore`
+- `/tests/test_agent_skill_workflow_contract.py`
+- `/phases/cpp-object-oriented-modular-refactoring/index.json`
+- `/phases/cpp-object-oriented-modular-refactoring/step1.md`
+- Step 0이 수정한 `/.codex/agents/implementation-agent.toml`
+
+## 작업
+
+Requirements `R-STYLE-001`과 `R-DOC-001`의 repository tooling만 구현한다.
+
+1. `/tests/test_cpp_policy_contract.py`에 `P-STYLE-001`을 먼저 작성한다. 다음 literal
+   contract를 검사한다.
+   - `.clang-format`: `BasedOnStyle: Google`, `IndentWidth: 2`, `ColumnLimit: 80`.
+   - `.clang-tidy`: C++17-compatible checks와 FESA PascalCase/snake_case identifier rules.
+   - `Doxyfile`: `INPUT = include src`, tests 제외, `WARN_AS_ERROR = YES`, generated HTML은
+     source control 밖의 build 경로.
+   - Root CMake의 optional `fesa_docs` target은 Doxygen가 발견될 때만 등록되고 default
+     configure에는 Doxygen를 요구하지 않는다.
+2. RED에서 설정 파일 부재로 test failure를 확인한다.
+3. `/.clang-format`, `/.clang-tidy`, `/Doxyfile`을 추가한다.
+4. `/CMakeLists.txt`에 `find_package(Doxygen QUIET)`와 발견 시에만 등록되는
+   `fesa_docs` custom target을 추가한다. Default build dependency에 넣지 않는다.
+5. Generated Doxygen HTML 경로가 ignore되지 않았다면 `/.gitignore`에 정확한 output
+   directory만 추가한다.
+6. Doxygen executable은 실행하지 않는다. 사용자가 문서 생성을 추후 수행하기로 했다.
+
+## Acceptance Criteria
+
+```powershell
+uv run --with pytest python -m pytest -v -rs tests/test_cpp_policy_contract.py
+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
+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
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Expected GREEN에는 Doxygen 실행이나 generated HTML이 포함되지 않는다.
+
+## 검증 및 상태 갱신
+
+- RED policy failure와 GREEN pytest/tool version/config/full CTest를 summary에 남긴다.
+- 성공 시 현재 Step만 `completed`로 갱신하고 생성한 설정 파일을 summary에 기록한다.
+- 환경에 두 LLVM executable이 없으면 `blocked`와 정확한 경로를 기록한다.
+- timestamp, retry, commit, advancement는 Executor 소유다.
+
+## 금지사항
+
+- 기존 C++를 format하지 마라. 이유: 기계적 migration은 Step 3–6 소유다.
+- Doxygen를 실행하거나 generated HTML을 commit하지 마라. 이유: 사용자 결정으로 생성은 연기됐다.
+- Doxygen를 default build 필수 dependency로 만들지 마라. 이유: 현재 blocking gate가 아니다.
+- 직접 commit하거나 hook script를 수동 실행하지 마라.