# FESA Repository Instructions

## 적용 범위와 기준 문서

이 파일은 저장소 전체에 적용한다.

- 제품 요구사항과 Phase 1 수용 조건은 `docs/PRD.md`를 따른다.
- 모듈 경계와 데이터 흐름은 `docs/ARCHITECTURE.md`를 따른다.
- 기술 선택과 트레이드오프는 `docs/ADR.md`를 따른다.
- Harness 실행 방법은 `docs/HARNESS.md`와 `.agents/skills/harness/SKILL.md`를 따른다.
- 실제 빌드와 테스트 명령은 `.harness/config.json`과 CMake Preset을 우선한다.

## 기술 기준

- 언어 표준: C++20
- 컴파일러: Visual Studio 2026 MSVC v145
- 대상 플랫폼: Windows x64
- 빌드 및 테스트: CMake, CMake Presets, CTest, GoogleTest/GoogleMock
- 수치 연산 및 희소 직접해법: Intel oneAPI MKL
- 요소 계산 및 조립 병렬화: Intel oneAPI TBB
- 결과 저장: HDF5
- 외부 라이브러리는 개발 환경에 사전 설치된 버전을 사용한다.
- FESA는 단위 변환을 수행하지 않는다. 입력은 일관 단위계를 사용해야 한다.

## Phase 1 범위

- Abaqus `.inp` 제한 부분집합으로 작성된 flat/orphan mesh 또는 좌표변환이 없는
  단일 Part/Assembly/Instance 모델을 읽는다.
- 단일 선형 정적 `*STEP`만 실행한다.
- 절점당 6자유도를 갖는 2절점 3D Isoparametric Timoshenko Beam만 구현한다.
- 등방성 선형 탄성, 일반 단면, `*BOUNDARY`, `*CLOAD`만 지원한다.
- 다른 요소, 다중 step, 여러 Instance, Instance 좌표변환, MPC, 분포하중, 비선형,
  동적, 모달, 좌굴 및 열전달을 선행 구현하지 않는다.

## 아키텍처 규칙

- public header는 `include/fesa/`, 구현은 `src/fesa/`, 테스트는 `tests/`에 둔다.
- `core`, `model`, `fem`, `elements`는 Abaqus, MKL, TBB 및 HDF5 API에 의존하지 않는다.
- `io/abaqus`는 입력 syntax와 semantic mapping만 담당하며 해석 알고리즘을 알지 않는다.
- `model`에는 Abaqus keyword 문자열 대신 solver semantic model을 저장한다.
- 자유도와 equation ID는 `DofManager`가 소유한다. `Node`나 `Element`에 분산 저장하지 않는다.
- 외부 라이브러리 handle과 resource는 adapter와 RAII wrapper 내부에 가둔다.
- 테스트 helper가 production parser, model validation 또는 solver 경로를 우회하지 않게 한다.
- 실제 두 번째 구현이 생기기 전에는 범용 registry, 빈 미래 클래스 또는 디렉터리를 만들지 않는다.

## 개발 및 검증 절차

1. 요구조건과 완료 기준을 먼저 문서화한다.
2. 정식화의 출처, 가정, 좌표계, 부호 및 적분 규칙을 기록한다.
3. 입력, semantic model 및 HDF5 계약을 구현 전에 확정한다.
4. 실패하는 단위·통합·reference 테스트와 모델을 먼저 작성한다.
5. 테스트를 통과하는 최소 코드를 구현한다.
6. 해석해, physics sanity 및 Abaqus 2024 골든 결과와 비교한다.
7. 물리량별 tolerance를 통과한 뒤에만 기능 완료와 내부 배포를 선언한다.

추가 규칙:

- 수직 파이프라인을 먼저 연결하되 임시 가짜 강성행렬은 사용하지 않는다.
- 같은 입력과 설정의 병렬 조립 결과는 재현 가능해야 한다.
- 전단강성이 생략되면 \(A_{sy}=A_{sz}=5A/6\)과 `SCF=0`을 Phase 1 기본값으로
  적용한다.
- reference 비교는 metadata 없이 요청된 물리량과 CSV 경로를 명시한다. 현재
  캔틸레버 샘플은 변위, 반력 및 요소 단면력을 비교하며 도심 응력 비교 루틴은
  synthetic CSV로 검증한다.
- 새 MSVC 빌드 경고를 추가하지 않는다.
- 변경은 요청 범위에 한정하고 Conventional Commits 형식의 메시지를 사용한다.

## 검증 명령

Harness Python 검증:

```powershell
uv run --with pytest python -m pytest -v -rs
```

테스트가 0개 수집된 실행은 성공으로 인정하지 않는다.

Solver bootstrap 이후에는 `.harness/config.json`에 지정된 CMake Preset을 사용한다.
Preset이 없을 때만 다음 격리 build directory를 사용한다.

```powershell
cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Harness phase 실행:

```powershell
python scripts/execute.py <phase-name>
```

사용자가 명시적으로 원격 push를 요청한 경우에만 다음을 사용한다.

```powershell
python scripts/execute.py <phase-name> --push
```