modify handoff.md

docs/HANDOFF.md

@@ -2,8 +2,8 @@
 
 ## 1. 문서 목적
 
-이 문서는 `solver-bootstrap` 완료 후 다음 세션에서
-`domain-and-input-skeleton` Phase를 바로 시작하기 위한 인수인계 기록이다.
+이 문서는 `domain-and-input-skeleton` 완료 후 새 세션에서
+`fem-and-beam-kernel` Phase를 바로 시작하기 위한 인수인계 기록이다.
 요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다.
 
 - `/AGENTS.md`
@@ -11,35 +11,72 @@
 - `/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/fem-and-beam-kernel/index.json`
+- `/phases/fem-and-beam-kernel/step0.md`부터 `step3.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는 없다.
+2026-07-31 확인 기준:
 
-`solver-bootstrap`에서 다음 기반이 구현되었다.
+- 현재 브랜치: `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에서
+  실제 구현과 함께 만든다.
 
-- Visual Studio 2026, MSVC v145, Windows x64용 CMake Preset
-- C++20 `fesa_core`와 `fesa` CLI 골격
+이 문서를 갱신하기 직전 작업 트리는 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와 workspace validation
+- Harness Python characterization test와 CMake/CTest 실행 계약
 
-## 3. 검증된 개발환경
+### `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 파일에 넣지 않는다.
+절대경로를 tracked CMake 파일이나 Preset에 넣지 않는다.
 
 ```powershell
 $env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl"
@@ -53,125 +90,188 @@ 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-31 위 네 경로가 모두 존재함을 확인했다. 같은 환경에서 다음 baseline을
+새로 검증했다.
 
-2026-07-30 `dev` baseline에서 다음 검증을 통과했다.
-
-- Debug configure와 build 성공
-- CTest 4개 중 4개 성공
+- MSVC v145 Debug build 성공, 새 경고 없음
+- CTest 12개 중 12개 성공
 - Harness pytest 20개 중 20개 성공
-- dependency smoke test에서 MKL 2026.1, TBB, HDF5와 GoogleTest runtime 확인
+- pytest가 실제로 20개를 수집했으므로 0-test 성공이 아님
 
 검증 명령:
 
 ```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`부터 다시 실행한다.
+CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저
+다음을 실행한다.
 
-## 4. 확정된 Phase 1 범위
+```powershell
+cmake --fresh --preset windows-debug
+```
 
-- 소변형 선형 정적해석과 단일 `*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
+## 5. 다음 Phase 목표와 Step 순서
 
-이번 Phase에서 여러 Instance, Instance 좌표변환, 다른 요소, 해석 equation 구성,
-Beam stiffness kernel, MKL solve와 HDF5 writer를 구현하지 않는다.
+`fem-and-beam-kernel`의 독립 deliverable은 실제 2절점 3D Timoshenko Beam의
+local/global stiffness와 해석적 sanity test다. 네 Step을 순서대로 실행한다.
 
-## 5. 입력 및 semantic model 결정사항
+### Step 0 — `quadrature-and-shape-functions`
 
-- `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`는 지원하지 않고 거부한다.
+- `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를 만들지 않는다.
 
-## 6. 다음 Phase 실행 순서
+### Step 1 — `dof-manager`
 
-Phase 정의는 `/phases/domain-and-input-skeleton/`에 있다.
+- 절점당 자유도 순서는
+  \(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 범위가 아니다.
 
-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 2 — `beam-local-frame`
 
-각 Step은 TDD 순서를 지킨다.
+- 두 절점과 mandatory orientation vector로 오른손 직교
+  `BeamFrame {ex, ey, ez}`를 만든다.
+- Gram-Schmidt, 정규화, 직교성, determinant \(+1\), 회전/에너지 invariant를
+  테스트한다.
+- zero length, zero orientation, 요소축과 평행한 orientation은 diagnostic으로
+  실패시킨다.
+- `Matrix12`는 현재 코드에 없으므로 이 Step의 transformation 계약에 필요한 최소
+  고정 크기 타입만 만든다. 범용 동적 matrix 계층이나 registry를 만들지 않는다.
 
-1. Step 파일과 선행 파일을 모두 읽는다.
-2. 요청된 동작을 보여주는 실패 테스트를 먼저 작성하고 실패를 확인한다.
-3. 테스트를 통과시키는 최소 구현만 추가한다.
-4. focused test와 전체 CTest를 실행한다.
-5. Harness가 Step 상태와 summary를 기록하게 한다.
+### Step 3 — `timoshenko-stiffness-kernel`
 
-Harness 실행 전에는 작업 트리가 clean이어야 한다. 이 `HANDOFF.md`를 포함한 필요한
-변경을 먼저 커밋하고 `dev`가 clean인지 확인한다.
+- 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 fetch origin
-git rev-parse dev
+git rev-parse HEAD
 git rev-parse origin/dev
-python scripts/execute.py domain-and-input-skeleton
 ```
 
-executor는 `feat-domain-and-input-skeleton` 브랜치를 생성하거나 checkout한다.
-원격 push는 사용자가 명시적으로 요청한 경우에만 `--push`를 사용한다.
+작업 트리가 clean이고 `dev`가 의도한 기준인지 확인한 뒤 4절의 package 환경 변수를
+설정하고 baseline을 실행한다. 그 다음:
 
-## 7. 구현 시 지켜야 할 경계
+```powershell
+python scripts/execute.py fem-and-beam-kernel
+```
 
-- 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를 만들지 않는다.
+executor는 `feat-fem-and-beam-kernel` 브랜치를 생성하거나 checkout하고 Step 상태와
+output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 `--push`를
+사용하지 않는다.
 
-## 8. Reference 검증 상태
+각 Step은 다음 순서를 지킨다.
 
-현재 샘플은 `/reference/cantilever beam/`에 있다.
+1. Step 파일의 필수 문서와 선행 구현을 모두 읽는다.
+2. 성공 기준과 수학 invariant를 명시한다.
+3. 실패 테스트를 먼저 작성하고 예상한 이유로 실패함을 확인한다.
+4. 테스트를 통과시키는 최소 production code만 구현한다.
+5. focused test, 전체 CTest, Harness pytest를 실행한다.
+6. Step summary와 output metadata가 실제 결과와 일치하는지 확인한다.
+7. Phase 종료 전 전체 diff를 아키텍처·정식화·테스트 기준으로 review한다.
 
-- Abaqus input
-- displacement CSV
-- reaction CSV
+## 9. 알려진 Harness 실행 이력과 복구 주의사항
 
-per-model metadata는 사용하지 않는다. 현재 샘플 검증은 변위와 반력만 요청한다.
-요소 내력과 요소 절점 단면 도심 `Sxx` CSV는 추후 추가한다. 다만 해당 CSV reader와
-비교 kernel은 이후 계획된 Phase에서 synthetic CSV로 함께 구현하고 검증해야 한다.
+이전 Phase에서 production 코드와 무관한 두 executor 문제가 있었다.
 
-## 9. 다음 Phase 완료 조건
+- 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와 수용 조건을 직접 수행해 완료했다.
 
-- `phases/domain-and-input-skeleton/index.json`의 Step 0~3이 모두 `completed`
-- `phases/index.json`에서 `domain-and-input-skeleton`이 `completed`
+새 세션에서는 이 상태가 여전히 유효하다고 단정하지 말고 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 경고 없음
-- flat fixture와 단일 무변환 Instance fixture가 동등한 활성 `Domain` 생성
-- 복합 origin 보존, 미참조 Part 제외와 미지원 scope/transform diagnostic 검증
-- 변경사항 review 후 `feat-domain-and-input-skeleton`을 `dev`에 병합
+- 강체운동, 해석해, 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를 시작해주세요.