docs: add solver core skeleton phase

2026-06-12 01:31:31 +09:00
parent 6646344113
commit 4e7fd1087d
11 changed files with 1100 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Step 0: cmake-ctest-bootstrap
+
+## 읽어야 할 파일
+
+먼저 아래 파일들을 읽고 프로젝트의 아키텍처와 검증 규칙을 파악하라:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/scripts/validate_workspace.py`
+
+## 작업
+
+C++ solver skeleton을 구현할 수 있도록 최소 CMake/CTest 부트스트랩을 만든다.
+
+요구사항:
+
+- 루트 `/CMakeLists.txt`를 생성한다.
+- C++ 표준은 C++17 이상으로 고정한다.
+- MSVC에서 warning-as-error를 강제하지 않는다.
+- 아직 production source가 없으므로 solver target은 `INTERFACE` library `fesa_core`로 시작한다.
+- `fesa_core`는 repository root의 `src`를 include directory로 노출한다.
+- `enable_testing()`과 `tests/` 하위 CMake 구성을 연결한다.
+- `/tests/CMakeLists.txt`, `/tests/unit/CMakeLists.txt`, `/tests/integration/CMakeLists.txt`를 생성한다.
+- `tests/unit/*_test.cpp`와 `tests/integration/*_test.cpp` 파일을 각각 독립 test executable로 등록한다.
+- 각 test executable은 `fesa_core`에 link한다.
+- `/tests/unit/harness_smoke_test.cpp`를 생성하고, 표준 라이브러리만 사용해 CTest가 동작함을 확인하는 최소 `main()`을 둔다.
+- npm, JavaScript, TypeScript fallback은 추가하지 않는다.
+
+권장 CMake 구조:
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(FESA LANGUAGES CXX)
+
+add_library(fesa_core INTERFACE)
+target_compile_features(fesa_core INTERFACE cxx_std_17)
+target_include_directories(fesa_core INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+enable_testing()
+add_subdirectory(tests)
+```
+
+`tests/unit/CMakeLists.txt`와 `tests/integration/CMakeLists.txt`는 `file(GLOB CONFIGURE_DEPENDS ...)`와 `foreach`를 사용해 새 `*_test.cpp`가 자동으로 CTest에 등록되도록 만든다.
+
+## Tests To Write First
+
+- `/tests/unit/harness_smoke_test.cpp`
+  - `main()`이 `std::string{"fesa"}.size() == 4` 같은 deterministic smoke assertion을 검증한다.
+  - 실패 시 non-zero를 반환한다.
+
+RED 확인:
+
+1. `tests/unit/harness_smoke_test.cpp`를 먼저 만든다.
+2. `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R harness_smoke_test`를 실행해 아직 CMake 구성이 없어 실패함을 확인한다.
+3. 그 뒤 CMake 파일을 작성한다.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R harness_smoke_test
+```
+
+## 검증 절차
+
+1. 위 AC 커맨드를 실행한다.
+2. 아키텍처 체크리스트를 확인한다:
+   - ARCHITECTURE.md의 `src/`, `tests/unit/` 구조를 따르는가?
+   - ADR-002의 C++17/MSVC/CMake/CTest 기본값을 벗어나지 않았는가?
+   - AGENTS.md의 `python scripts/validate_workspace.py` 기본 검증 경로를 유지하는가?
+3. 결과에 따라 `phases/solver-core-skeleton/index.json`의 step 0을 업데이트한다:
+   - 성공: `"status": "completed"`, `"summary": "CMake/CTest bootstrap with fesa_core interface target and smoke test"`
+   - 3회 수정 시도 후 실패: `"status": "error"`, `"error_message": "구체적 에러 내용"`
+   - 사용자 개입 필요: `"status": "blocked"`, `"blocked_reason": "구체적 사유"` 후 중단
+
+## 금지사항
+
+- C++ production solver class를 이 step에서 만들지 마라.
+- 외부 test framework를 추가하지 마라.
+- JavaScript/TypeScript/npm fallback을 추가하지 마라.