FESA/docs/HANDOFF.md

# FESA Session Handoff

## 1. 문서 목적

이 문서는 `solver-bootstrap` 완료 후 다음 세션에서
`domain-and-input-skeleton` Phase를 바로 시작하기 위한 인수인계 기록이다.
요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다.

- `/AGENTS.md`
- `/docs/PRD.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/HARNESS.md`
- `/docs/superpowers/specs/2026-07-29-abaqus-assembly-reference-design.md`
- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md`

내용이 충돌하면 위 기준 문서와 `phases/`의 현재 상태를 우선한다.

## 2. 현재 저장소 상태

- 기준 브랜치: `dev`
- 원격 브랜치: `origin/dev`
- `solver-bootstrap`이 병합된 기준 커밋:
  `8faaf4db9948f7a83f9341397d2a4177dce51fd7`
- 완료 Phase: `solver-bootstrap`
- 다음 Phase: `domain-and-input-skeleton`
- 다음 Step: `0 - semantic-domain-and-origin-types`
- `domain-and-input-skeleton`의 네 Step은 모두 `pending`이다.
- 활성 blocker는 없다.

`solver-bootstrap`에서 다음 기반이 구현되었다.

- Visual Studio 2026, MSVC v145, Windows x64용 CMake Preset
- C++20 `fesa_core`와 `fesa` CLI 골격
- MKL, TBB, HDF5, GoogleTest package discovery와 dependency smoke test
- typed entity ID, `Vec3`, source location, diagnostic, status 값 타입
- Harness Python characterization test와 workspace validation

## 3. 검증된 개발환경

새 PowerShell 세션에서 configure 또는 Harness 실행 전에 다음 환경 변수를 설정한다.
절대경로를 tracked CMake 파일에 넣지 않는다.

```powershell
$env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl"
$env:TBB_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\tbb"
$env:HDF5_DIR = "C:\Program Files\HDF_Group\HDF5\2.1.1\cmake"
$env:GTest_DIR = "C:\Users\baram\AppData\Local\FESA\dependencies\googletest-1.17.0-v145-x64-crt\lib\cmake\GTest"

Test-Path "$env:MKL_DIR\MKLConfig.cmake"
Test-Path "$env:TBB_DIR\TBBConfig.cmake"
Test-Path "$env:HDF5_DIR\hdf5-config.cmake"
Test-Path "$env:GTest_DIR\GTestConfig.cmake"
```

네 확인 결과가 모두 `True`여야 한다. GoogleTest 원본 clone은
`C:\git\googletest`에 있지만 FESA configure에는 v145/x64/CRT 조건으로 설치한 위
package directory를 사용한다.

2026-07-30 `dev` baseline에서 다음 검증을 통과했다.

- Debug configure와 build 성공
- CTest 4개 중 4개 성공
- Harness pytest 20개 중 20개 성공
- dependency smoke test에서 MKL 2026.1, TBB, HDF5와 GoogleTest runtime 확인

검증 명령:

```powershell
cmake --fresh --preset windows-debug
cmake --build --preset windows-debug
ctest --preset windows-debug --output-on-failure
uv run --with pytest python -m pytest -v -rs
```

환경 변수를 설정하지 않은 불완전한 CMake cache에서는
`ALL_BUILD.vcxproj`가 없다는 빌드 오류가 발생할 수 있다. 이 경우 위 환경 변수를
먼저 설정하고 `cmake --fresh --preset windows-debug`부터 다시 실행한다.

## 4. 확정된 Phase 1 범위

- 소변형 선형 정적해석과 단일 `*STEP`, `*STATIC`
- 절점당 6자유도를 갖는 2절점 3D Isoparametric Timoshenko Beam
- 등방성 선형 탄성, 일반 Beam 단면, `*BOUNDARY`, `*CLOAD`
- Abaqus 2024 `.inp` 제한 부분집합
- flat/orphan mesh 또는 좌표변환이 없는 단일 Assembly·단일 Instance
- C++20, MSVC v145, MKL PARDISO, oneTBB, HDF5

이번 Phase에서 여러 Instance, Instance 좌표변환, 다른 요소, 해석 equation 구성,
Beam stiffness kernel, MKL solve와 HDF5 writer를 구현하지 않는다.

## 5. 입력 및 semantic model 결정사항

- `io/abaqus`는 syntax와 scope를 보존하고 해석 알고리즘을 알지 않는다.
- `model`은 Abaqus keyword record가 아니라 정규화된 solver semantic model을
  소유한다.
- 계층형 입력에서는 모든 Part를 파싱하되 Assembly의 단일 Instance가 참조하는
  Part만 `Domain`에 포함한다.
- 외부 entity는 `(instance name, part-local label)` 복합 식별자를 사용하고 내부
  dense ID와 분리한다.
- flat mesh는 `part_name`과 `instance_name`을 빈 값으로 표현한다.
- 여러 Assembly/Instance, Instance transform, instance-local mesh 수정과
  flat/계층 mesh 혼합은 source location이 포함된 diagnostic으로 거부한다.
- `Domain`은 build 이후 불변으로 취급한다.
- equation ID를 `Node`나 `Element`에 저장하지 않는다.
- `*TRANSVERSE SHEAR STIFFNESS`가 생략되면
  \(A_{sy}=A_{sz}=5A/6\), `SCF=0`과
  `ShearPropertySource::phase1_default`를 적용한다.
- 명시된 nonzero `SCF`는 지원하지 않고 거부한다.

## 6. 다음 Phase 실행 순서

Phase 정의는 `/phases/domain-and-input-skeleton/`에 있다.

1. `step0.md` — semantic domain과 entity origin 값 타입
2. `step1.md` — `DomainBuilder` validation과 불변 `Domain`
3. `step2.md` — Part/Assembly/Instance scope를 보존하는 Abaqus syntax parser
4. `step3.md` — flat 또는 단일 활성 Instance를 동일한 `Domain`으로 정규화

각 Step은 TDD 순서를 지킨다.

1. Step 파일과 선행 파일을 모두 읽는다.
2. 요청된 동작을 보여주는 실패 테스트를 먼저 작성하고 실패를 확인한다.
3. 테스트를 통과시키는 최소 구현만 추가한다.
4. focused test와 전체 CTest를 실행한다.
5. Harness가 Step 상태와 summary를 기록하게 한다.

Harness 실행 전에는 작업 트리가 clean이어야 한다. 이 `HANDOFF.md`를 포함한 필요한
변경을 먼저 커밋하고 `dev`가 clean인지 확인한다.

```powershell
git switch dev
git status --short --branch
git fetch origin
git rev-parse dev
git rev-parse origin/dev
python scripts/execute.py domain-and-input-skeleton
```

executor는 `feat-domain-and-input-skeleton` 브랜치를 생성하거나 checkout한다.
원격 push는 사용자가 명시적으로 요청한 경우에만 `--push`를 사용한다.

## 7. 구현 시 지켜야 할 경계

- public header는 `include/fesa/`, 구현은 `src/fesa/`, 테스트는 `tests/`에 둔다.
- `core`와 `model` public API에 Abaqus, MKL, TBB 또는 HDF5 타입을 노출하지 않는다.
- parser record를 `Domain`에 저장하지 않는다.
- parser 단계에서 active Part를 선택하거나 `Domain`을 생성하지 않는다.
- semantic mapper가 Instance transform을 조용히 무시하지 않게 한다.
- 잘못된 model 값을 자동 보정하지 않고 가능한 diagnostic을 수집한다.
- public mutable `Domain` accessor를 추가하지 않는다.
- 여러 Instance container, 범용 factory/registry와 미래 기능용 빈 클래스를 만들지
  않는다.
- production parser와 validation 경로를 우회하는 test helper를 만들지 않는다.

## 8. Reference 검증 상태

현재 샘플은 `/reference/cantilever beam/`에 있다.

- Abaqus input
- displacement CSV
- reaction CSV

per-model metadata는 사용하지 않는다. 현재 샘플 검증은 변위와 반력만 요청한다.
요소 내력과 요소 절점 단면 도심 `Sxx` CSV는 추후 추가한다. 다만 해당 CSV reader와
비교 kernel은 이후 계획된 Phase에서 synthetic CSV로 함께 구현하고 검증해야 한다.

## 9. 다음 Phase 완료 조건

- `phases/domain-and-input-skeleton/index.json`의 Step 0~3이 모두 `completed`
- `phases/index.json`에서 `domain-and-input-skeleton`이 `completed`
- focused test와 전체 CTest 통과
- Harness pytest가 0개가 아닌 상태로 전체 통과
- 새 MSVC 경고 없음
- flat fixture와 단일 무변환 Instance fixture가 동등한 활성 `Domain` 생성
- 복합 origin 보존, 미참조 Part 제외와 미지원 scope/transform diagnostic 검증
- 변경사항 review 후 `feat-domain-and-input-skeleton`을 `dev`에 병합