# 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를 수동 실행하지 마라.