FESA/docs/HANDOFF.md

# FESA Session Handoff

## 1. 문서 목적

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

- `/AGENTS.md`
- `/docs/PRD.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/HARNESS.md`
- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md`
- `/phases/fem-and-beam-kernel/index.json`
- `/phases/fem-and-beam-kernel/step0.md`부터 `step3.md`

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

## 2. 현재 저장소 상태

2026-07-31 확인 기준:

- 현재 브랜치: `dev`
- `dev`, `origin/dev`, `origin/HEAD` 기준 커밋:
  `e7f0d53406bfdff0fbd610c2b595a8d214341353`
- 완료 Phase:
  - `solver-bootstrap`
  - `domain-and-input-skeleton`
- 다음 Phase: `fem-and-beam-kernel`
- 다음 Step: `0 - quadrature-and-shape-functions`
- `fem-and-beam-kernel`의 Step 0~3은 모두 `pending`
- 활성 제품 코드 blocker는 없다.
- `include/fesa/fem/`, `include/fesa/elements/beam/`,
  `docs/formulation/timoshenko-beam-3d.md`는 아직 존재하지 않는다. 해당 Step에서
  실제 구현과 함께 만든다.

이 문서를 갱신하기 직전 작업 트리는 clean이었다. 문서 수정 자체가 아직 커밋되지 않은
경우 Harness 실행 전에 `docs/HANDOFF.md` 변경을 먼저 커밋하거나 별도로 정리해야 한다.

## 3. 완료된 기반

### `solver-bootstrap`

- Visual Studio 2026 MSVC v145, Windows x64, C++20 CMake Preset
- `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와 CMake/CTest 실행 계약

### `domain-and-input-skeleton`

- solver semantic 값 타입:
  - `Node`, `BeamElement`, `IsotropicElastic`, `BeamSection`
  - `NodeSet`, `ElementSet`, `StepDefinition`
  - `EntityOrigin`과 typed internal ID
- build 이후 const view만 제공하는 `Domain`
- `DomainBuilder`의 중복 ID/origin, 참조, 유한값, 물성, 길이, orientation,
  경계조건 검증
- flat/orphan mesh와 Part/Assembly/단일 무변환 Instance scope를 보존하는 Abaqus
  syntax parser
- 활성 Part만 선택해 flat `Domain`으로 정규화하는 semantic mapper
- 실제 Part/Instance/local label provenance 보존
- 생략된 전단강성에
  \(A_{sy}=A_{sz}=5A/6\)과
  `ShearPropertySource::phase1_default` 적용
- 여러 Instance, Instance transform, missing Part 등 최소 조직 오류의 source
  diagnostic
- public parser/mapper 경로를 사용하는 flat/계층형 통합 테스트

현재 parser/mapper는 다음 Phase의 Beam kernel 테스트에 필요한 최소 semantic
`Domain`을 제공한다. 전체 Abaqus 부분집합, nested/`GENERATE` set, 완전한 scope
resolution, explicit transverse shear, no-op directive와 단일 step의 모든 option은
후속 `abaqus-subset-completion` Phase 책임이다. 이번 Phase에서 선행 구현하지 않는다.

## 4. 검증된 개발환경과 baseline

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

```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"
```

2026-07-31 위 네 경로가 모두 존재함을 확인했다. 같은 환경에서 다음 baseline을
새로 검증했다.

- MSVC v145 Debug build 성공, 새 경고 없음
- CTest 12개 중 12개 성공
- Harness pytest 20개 중 20개 성공
- pytest가 실제로 20개를 수집했으므로 0-test 성공이 아님

검증 명령:

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

CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저
다음을 실행한다.

```powershell
cmake --fresh --preset windows-debug
```

## 5. 다음 Phase 목표와 Step 순서

`fem-and-beam-kernel`의 독립 deliverable은 실제 2절점 3D Timoshenko Beam의
local/global stiffness와 해석적 sanity test다. 네 Step을 순서대로 실행한다.

### Step 0 — `quadrature-and-shape-functions`

- `fem`에 1점/2점 1D Gauss rule, 2절점 선형 shape function과 derivative,
  `length/2` Jacobian을 구현한다.
- partition of unity, endpoint interpolation, derivative sum zero, 적분 정확도,
  invalid order/length를 실패 테스트로 먼저 고정한다.
- runtime registry나 Beam stiffness를 만들지 않는다.

### Step 1 — `dof-manager`

- 절점당 자유도 순서는
  \(u_x,u_y,u_z,r_x,r_y,r_z\)의 6개다.
- `DofManager`가 full DOF, constrained/free equation numbering,
  12개 요소 DOF mapping과 prescribed value를 포함한 full-vector reconstruction을
  전담한다.
- external label이나 입력 선언 순서에 흔들리지 않는 deterministic numbering을
  테스트로 고정한다.
- equation ID를 `Node`나 `BeamElement`에 저장하지 않는다.
- sparse pattern, MPC, penalty DOF는 이 Step 범위가 아니다.

### Step 2 — `beam-local-frame`

- 두 절점과 mandatory orientation vector로 오른손 직교
  `BeamFrame {ex, ey, ez}`를 만든다.
- Gram-Schmidt, 정규화, 직교성, determinant \(+1\), 회전/에너지 invariant를
  테스트한다.
- zero length, zero orientation, 요소축과 평행한 orientation은 diagnostic으로
  실패시킨다.
- `Matrix12`는 현재 코드에 없으므로 이 Step의 transformation 계약에 필요한 최소
  고정 크기 타입만 만든다. 범용 동적 matrix 계층이나 registry를 만들지 않는다.

### Step 3 — `timoshenko-stiffness-kernel`

- production code보다 먼저
  `/docs/formulation/timoshenko-beam-3d.md`를 작성한다.
- 문서에는 최소한 다음을 고정한다.
  - 12개 local/global DOF와 component 순서
  - 오른손 국부 좌표계 정의
  - 변형률과 부호 규약
  - \(G=E/[2(1+\nu)]\)와 constitutive matrix
  - 자연좌표, shape derivative와 \(J=L/2\)
  - 축·굽힘·비틀림 2점, 전단 1점 선택적 감차적분
  - local/global transformation 규칙
- 실제 `Beam3D2Input`, `Beam3D2Contribution`, `compute_beam3d2` kernel을 구현한다.
- 대칭성, 강체운동 zero energy, 축/비틀림/단축·이축 굽힘 해석해,
  shear-dominant 문제, 세장비 sweep과 회전 invariant를 실패 테스트로 먼저 만든다.
- 임시 가짜/닫힌형 stiffness로 파이프라인만 통과시키지 않는다.

## 6. 수치·정식화 계약

- 요소: 2절점 직선 3D Isoparametric Timoshenko Beam
- 절점당 6 DOF:
  \(u_x,u_y,u_z,\theta_x,\theta_y,\theta_z\)
- 선형 shape function, \(\xi\in[-1,1]\)
- 축·굽힘·비틀림: 2점 Gauss 적분
- 전단: 1점 Gauss 적분
- 재료: 등방성 선형 탄성,
  \(G=E/[2(1+\nu)]\)
- 단면:
  \(A,I_y,I_z,J,A_{sy},A_{sz}\)
- 제한:
  \(I_{yz}=0\), 도심/전단중심 일치, offset/warping 없음
- orientation은 필수이며 자동 추측하거나 임의 축으로 대체하지 않는다.
- tolerance는 테스트 이름이나 주석에 수학적/scale-aware 근거를 기록한다.
- FESA는 단위 변환을 하지 않는다.

정식화는 `docs/PRD.md` 3.2절, `docs/ARCHITECTURE.md` 8절,
`docs/ADR.md` ADR-005와 ADR-014를 우선한다.

## 7. 아키텍처 경계와 이번 Phase 제외 범위

- public header는 `include/fesa/`, 구현은 `src/fesa/`, 테스트는 `tests/`에 둔다.
- `core`, `model`, `fem`, `elements`는 Abaqus, MKL, TBB, HDF5 API에 의존하지
  않는다.
- `fem`은 DOF, equation mapping, quadrature, shape function, Jacobian,
  local/global mapping만 담당한다.
- `elements/beam`은 Beam local contribution과 kernel 계약을 담당한다.
- `Domain`은 읽기 전용 view로 사용하고 복제하거나 mutable accessor를 추가하지 않는다.
- 이번 Phase에서는 다음을 구현하지 않는다.
  - sparse COO/CSR pattern과 조립
  - essential BC elimination system
  - MKL PARDISO solve
  - oneTBB parallel assembly
  - HDF5 writer와 result recovery
  - 여러 요소 타입을 위한 registry/factory
  - 비선형, warping, offset, \(I_{yz}\ne0\), 여러 Instance

## 8. 새 세션 시작 절차

먼저 이 문서와 Step 파일을 읽고 현재 상태를 재검증한다.

```powershell
git switch dev
git status --short --branch
git rev-parse HEAD
git rev-parse origin/dev
```

작업 트리가 clean이고 `dev`가 의도한 기준인지 확인한 뒤 4절의 package 환경 변수를
설정하고 baseline을 실행한다. 그 다음:

```powershell
python scripts/execute.py fem-and-beam-kernel
```

executor는 `feat-fem-and-beam-kernel` 브랜치를 생성하거나 checkout하고 Step 상태와
output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 `--push`를
사용하지 않는다.

각 Step은 다음 순서를 지킨다.

1. Step 파일의 필수 문서와 선행 구현을 모두 읽는다.
2. 성공 기준과 수학 invariant를 명시한다.
3. 실패 테스트를 먼저 작성하고 예상한 이유로 실패함을 확인한다.
4. 테스트를 통과시키는 최소 production code만 구현한다.
5. focused test, 전체 CTest, Harness pytest를 실행한다.
6. Step summary와 output metadata가 실제 결과와 일치하는지 확인한다.
7. Phase 종료 전 전체 diff를 아키텍처·정식화·테스트 기준으로 review한다.

## 9. 알려진 Harness 실행 이력과 복구 주의사항

이전 Phase에서 production 코드와 무관한 두 executor 문제가 있었다.

- Step 2 child sandbox에서 MSBuild가 사용자 profile의 Microsoft SDK/FileTracker
  경로를 읽거나 child compiler process를 실행하지 못했다. 같은 checkout의 root
  PowerShell에서는 정확한 build와 focused/full CTest가 통과했다.
- Step 3 child Codex 실행은 2026-07-30 usage limit에 도달해
  `2026-08-05 15:07` 이후 재시도하라는 응답을 냈다. 당시 Step은 root 세션에서
  TDD와 수용 조건을 직접 수행해 완료했다.

새 세션에서는 이 상태가 여전히 유효하다고 단정하지 말고 Harness를 한 번 정상
실행해 확인한다. 같은 외부 문제가 반복되면:

1. 저장소 변경 전후 상태와 정확한 실패 stage를 보존한다.
2. 제품 코드 문제인지 child sandbox/quota 문제인지 root의 동일 명령으로 분리한다.
3. 수동 fallback 시에도 Step의 TDD, focused/full test, review를 생략하지 않는다.
4. 실패 output을 성공으로 위장하지 말고 이후 성공 증거와 복구 commit을 분리해
   metadata와 Git 이력에 남긴다.
5. 광범위한 사용자 profile 경로를 `--codex-add-dir`로 허용하지 않는다.

## 10. 다음 Phase 완료 조건

- `phases/fem-and-beam-kernel/index.json`의 Step 0~3이 모두 `completed`
- `phases/index.json`에서 `fem-and-beam-kernel`이 `completed`
- formulation 문서와 production kernel의 DOF, 좌표계, 부호, 적분 규칙 일치
- focused test와 전체 CTest 통과
- Harness pytest가 0개가 아닌 상태로 전체 통과
- 새 MSVC 경고 없음
- 강체운동, 해석해, shear-dominant, 세장비와 회전 invariant 검증 통과
- `fem`/`elements`에 Abaqus 또는 외부 library API 유입 없음
- 코드 review의 Critical/Important 항목 해결
- 사용자 선택 전 원격 push나 `dev` 병합을 수행하지 않음

새 세션의 권장 첫 요청:

> `docs/HANDOFF.md`와 `phases/fem-and-beam-kernel/step0.md`부터 `step3.md`를 읽고
> 현재 baseline을 확인한 뒤 `fem-and-beam-kernel` Phase를 시작해주세요.