# Project: FESA Structural Solver

## 기술 스택
- C++17 이상
- MSVC on Windows
- CMake + CTest
- Python 3 Harness scripts
- Intel oneAPI MKL, Intel oneAPI TBB
- HDF5 result storage
- Abaqus `.inp` keyword subset input

## 프로젝트 정체성
- FESA는 유한요소법 기반 구조해석 솔버 개발 프로젝트이다.
- Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다.
- 문서와 구현은 full Abaqus compatibility를 주장하지 않는다. 기능별로 승인된 Abaqus keyword subset만 지원한다.
- 공식 solver output은 HDF5 `results.h5`이다.
- reference 결과는 FESA와 같은 Abaqus `.inp` 모델을 Abaqus로 해석해 생성한 CSV 파일이다.
- reference comparison은 FESA `results.h5`의 변위, 반력, 내력, 응력 dataset을 `reference/<model-id>/<model-id>_*.csv` 파일과 비교한다.
- CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다.

## 아키텍처 규칙
- CRITICAL: 기본 검증 경로는 `python scripts/validate_workspace.py`이다.
- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다.
- CRITICAL: `harness-workflow` 스킬은 사용자가 명시적으로 허용하기 전까지 사용하지 않는다.
- Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
- AnalysisModel은 현재 step에서 활성화된 elements, loads, boundary conditions, properties/materials의 view를 제공하며 Domain을 복사하지 않는다.
- DofManager는 node별 자유도 정의, constrained/free mapping, equation numbering, sparse pattern ownership을 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.
- AnalysisState는 displacement, velocity, acceleration, temperature, external/internal force, residual, time/increment/iteration, element state를 소유한다.
- MKL, TBB, HDF5 API는 solver core에 직접 노출하지 않는다. `LinearSolver`, `ParallelFor`, `ResultsWriter`, `Vector`, `Matrix`, `SparseMatrix` adapter 경계 뒤에 둔다.
- Codex custom agent의 `model_reasoning_effort` 기본값은 `extra high`로 둔다.
- Harness runner는 `scripts/execute.py`에 둔다.
- `scripts/execute.py`는 `codex/<phase-name>` branch prefix만 사용한다.
- `scripts/execute.py` 실행 전 worktree는 clean 상태여야 한다.
- 각 phase step은 non-empty `allowed_paths`를 선언해야 한다.
- runner는 explicit allowed path와 runner housekeeping file만 stage하며 broad staging을 사용하지 않는다.
- runner가 만드는 모든 commit 전에는 Harness Python self-test와 `python scripts/validate_workspace.py`가 통과해야 한다.
- Codex hook 정책은 `.codex/hooks/`에 둔다.
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.

## 개발 프로세스
- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다.
- 기능 개발은 다음 gate를 순서대로 통과해야 한다.
  1. 요구조건 분석
  2. 연구자료 조사
  3. 유한요소 정식화
  4. 수치 검토
  5. I/O 계약 정의
  6. reference model 계약 준비
  7. C++ 구현
  8. build/test 검증
  9. reference comparison
  10. physics sanity
  11. release readiness
- 커밋 전 hook은 Harness Python self-test와 workspace validation을 실행해야 한다.
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
- Codex는 작업 완료 후 검증을 마치면 즉시 변경사항을 commit하고 push한다.
- 계획이 필요한 장기 작업은 Harness phase로 나누고, 각 step은 독립 실행 가능해야 한다.

## Agent/Skill Workflow
| 개발 과정 | Agent | Skill | 산출물 |
| --- | --- | --- | --- |
| 요구조건 분석 | `requirement-agent` | `fesa-requirements-baseline` | `docs/requirements/<feature-id>.md` |
| 연구자료 조사 | `research-agent` | `fesa-research-evidence`, `fem-theory-query` | `docs/research/<feature-id>-research.md` |
| 유한요소 정식화 | `formulation-agent` | `fesa-formulation-spec` | `docs/formulations/<feature-id>-formulation.md` |
| 수치 검토 | `numerical-review-agent` | `fesa-numerical-review` | `docs/numerical-reviews/<feature-id>-review.md` |
| I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `docs/io-definitions/<feature-id>-io.md` |
| reference model | `reference-model-agent` | `fesa-reference-models` | `docs/reference-models/<feature-id>-reference-models.md` |
| 구현 계획/구현 | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd` | tests, source, implementation report |
| build/test | `build-test-executor-agent` | `fesa-cpp-msvc-tdd` | `docs/build-test-reports/<feature-id>.md` |
| correction | `correction-agent` | `fesa-cpp-msvc-tdd` | `docs/corrections/<feature-id>.md` |
| reference 비교 | `reference-verification-agent` | `fesa-reference-comparison` | `docs/reference-verifications/<feature-id>-reference-verification.md` |
| 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `docs/physics-evaluations/<feature-id>-physics-evaluation.md` |
| 배포 준비 | `release-agent` | `fesa-release-readiness` | `docs/releases/<feature-id>-release.md` |

## 명령어
```bash
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push
```

## MSVC 검증 기본값
- Generator: `Visual Studio 17 2022`
- Platform: `x64`
- Config: `Debug`
- Build directory: `build/msvc-debug`

Override variables:
- `HARNESS_VALIDATION_COMMANDS`
- `HARNESS_CMAKE_GENERATOR`
- `HARNESS_CMAKE_PLATFORM`
- `HARNESS_CMAKE_CONFIG`
- `HARNESS_BUILD_DIR`