FESA/docs/HANDOFF.md

FESA Session Handoff

1. 목적과 기준 문서

이 문서는 beam-reference-qualification 완료 후 새 세션에서 마지막 Phase 1 단계인 internal-release를 시작하기 위한 인수인계 기록이다. 과거 phase의 구현 역사를 반복하기보다 현재 기준선, 검증 결과, 남은 작업과 실행 순서를 제공한다.

다음 문서를 우선 기준으로 사용한다.

• AGENTS.md
• docs/PRD.md
• docs/ARCHITECTURE.md
• docs/ADR.md
• docs/HARNESS.md
• docs/HDF5_SCHEMA.md
• docs/ABAQUS_INPUT_SUBSET.md
• docs/formulation/timoshenko-beam-3d.md
• docs/VALIDATION.md
• phases/internal-release/index.json
• phases/internal-release/step0.md부터 step4.md

내용이 충돌하면 AGENTS.md, PRD/ADR/아키텍처, 완료된 phase metadata와 실제 테스트를 우선한다. 특히 internal-release의 기존 Step 0과 Step 4에 남아 있는 reference 범위 설명은 4절의 최신 계약으로 바로잡은 뒤 release evidence에 사용한다.

2. Git과 Phase 상태

2026-08-03 기준 구현 상태는 다음과 같다.

• 기준 브랜치: dev
• 이 문서 갱신 직전 구현 HEAD: 6bc7cc3adadded6f1a2a0ed45449b2264c0f7a4e
• feat-beam-reference-qualification은 dev에 fast-forward 병합된 뒤 로컬에서 삭제됐다.
• internal-release를 제외한 phases/index.json의 모든 phase가 completed다.
• 다음 Phase: internal-release
• 다음 Step: Step 0 release-checklist
• Step 0부터 Step 4까지 모두 pending이다.
• 이 문서의 갱신은 구현 기준선 다음의 docs-only commit이다.

새 세션에서는 기록된 hash를 강제로 맞추지 말고 로컬과 원격의 실제 상태를 먼저 확인한다. 이 HANDOFF commit이 push된 뒤에는 dev와 origin/dev가 같은 commit을 가리켜야 한다.

git switch dev
git status --short --branch
git rev-parse HEAD
git rev-parse origin/dev
git rev-list --left-right --count origin/dev...dev

reset, rebase 또는 force push로 차이를 숨기지 않는다. 예상하지 못한 변경이 있으면 소유자를 확인하고 보존한다.

3. 완료된 Phase 1 기준선

현재 production 경로는 다음 기능을 제공한다.

• Abaqus .inp 제한 부분집합의 flat/orphan mesh 또는 좌표변환이 없는 단일 Part/Assembly/Instance 모델 파싱과 semantic validation
• 2절점 3D Isoparametric Timoshenko Beam, 등방성 선형 탄성, 일반 단면, *BOUNDARY, *CLOAD, 단일 선형 정적 Step
• MSVC v145, Intel oneAPI MKL PARDISO와 TBB를 사용하는 Windows x64 해석 경로
• canonical contribution ordering에 기반한 결정론적 병렬 요소 평가와 조립
• 원래 full equation에서 변위, 반력과 평형을 복구하는 선형 정적 해석
• 두 요소 끝의 section strain, section force, centroid/recovery-point Sxx 회복
• node/element provenance, component와 좌표계 metadata를 포함한 완전한 ResultDatabase
• 입력 원본 없이 model, analysis와 결과를 재구성할 수 있는 HDF5 schema 2.0.0
• 변위, 반력, 요소 단면력용 Abaqus CSV adapter와 component별 상관성 보고 CLI

결과 계약과 Beam reference phase의 세부 완료 기록은 다음 파일에 있다.

• phases/result-contract-completion/index.json
• phases/beam-reference-qualification/index.json
• docs/HDF5_SCHEMA.md
• docs/VALIDATION.md

internal-release에서는 위 solver 계약을 다시 설계하지 않는다. 설치, clean consumer, scale measurement와 release evidence에 필요한 최소 변경만 수행한다.

4. 검증 상태와 남은 제한

4.1 이중 검증 gate

docs/VALIDATION.md가 검증 결과의 단일 상세 보고서다.

• Gate A — FESA 정식화 적합성: PASS
• Gate B — Abaqus 결과 상관성: EVALUABLE

Gate A는 해석해, strain energy, 강체 mode, 회전 불변성, 평형과 결정성을 엄격한 tolerance로 검증한다. Gate B는 Abaqus B31과 FESA 정식화의 차이를 인정하고 component별 RMSE와 Relative L2를 보고한다. Gate B의 EVALUABLE은 모든 요청 entity/component가 유일하게 매칭되고 metric이 유한하다는 뜻이며, 임의의 상관성 pass/fail threshold를 통과했다는 뜻은 아니다.

현재 cantilever reference의 주요 Relative L2는 다음과 같다.

결과	Component	Relative L2
displacement	Uz	0.0022349969291714038
displacement	Ry	0.0000010416581667076092
reaction	RFz	4.4393520322089023e-13
reaction	RMy	2.591919334788851e-13
internal force	Vz	2.7107472798172426e-13
internal force	My	0.082541022764834646

18개 전체 component의 count, RMSE와 Relative L2는 docs/VALIDATION.md를 사용한다.

4.2 Reference 모델과 축 매핑

• Abaqus provenance는 reference/cantilever beam/cantilever beam.inp와 세 CSV다.
• Abaqus 원본 모델의 SCF=0.25는 보존한다.
• FESA projection은 reference/cantilever beam/cantilever beam fesa.inp이며 다른 의미 입력을 유지하고 SCF=0을 사용한다.
• FESA에 Abaqus SCF 보정이나 결과 맞춤 계수를 추가하지 않는다.

요소력 CSV는 다음 순서로 매핑한다.

FESA	Abaqus CSV
N	SF1
Vy	SF3
Vz	SF2
T	SM3
My	SM1
Mz	SM2

4.3 아직 완료되지 않은 검증

• 실제 Abaqus 결과로 검증된 물리량은 변위, 반력과 요소 단면력이다.
• Abaqus 도심 응력 CSV는 제공되지 않았다. StressCsv는 synthetic fixture로 schema와 entity mapping만 검증했으며 응력은 not yet Abaqus-qualified다.
• synthetic internal-force fixture도 adapter 단위 검증에 계속 사용하지만, 요소 단면력 자체는 별도의 실제 Abaqus golden CSV와 상관성 비교가 완료됐다.
• 내부 배포용 Release build, install tree, clean consumer smoke test와 약 100,000 DOF 측정은 아직 실행되지 않았다. 증거 없이 완료 표시하지 않는다.

4.4 internal-release Step 문서의 계약 불일치

phases/internal-release/step0.md와 step4.md에는 beam reference phase 이전의 문구가 남아 있다.

• “현재 Abaqus displacement/reaction comparison”은 변위·반력·요소 단면력 correlation으로 갱신해야 한다.
• “내력·응력은 synthetic coverage”라는 묶음 표현은 요소 단면력과 응력을 분리해야 한다. 요소 단면력은 real golden correlation과 synthetic adapter coverage가 모두 있고, 응력만 synthetic adapter coverage다.

새 세션은 Harness 실행 전에 이 두 Step 문서와 관련 checklist 문구를 현재 docs/PRD.md 8절 및 docs/VALIDATION.md와 일치시켜야 한다. 이 정렬은 검증 범위의 확장이 아니라 이미 완료된 증거를 정확히 기술하는 작업이다.

5. 다음 Phase: internal-release

Phase metadata는 phases/internal-release/index.json에 있다. Step은 순서대로 실행한다.

Step 0 — release-checklist

• docs/BUILDING.md, docs/INPUT_FORMAT.md, docs/RELEASE_CHECKLIST.md를 작성한다.
• PRD 8절의 각 내부 배포 기준에 고유 checklist ID를 부여한다.
• 실제 target, preset, example과 evidence command를 CMake에서 재확인한다.
• 미실행 Release/install/benchmark 항목을 완료 표시하지 않는다.
• 4.4절의 stale reference 문구를 먼저 바로잡는다.

Step 1 — cmake-install-package

• cmake --install로 내부 배포용 install tree를 만든다.
• CLI, fesa_core, public headers, CMake package config, example, schema/input/validation 문서와 runtime DLL inventory를 포함한다.
• install config에 absolute build path가 남는 실패 검사를 먼저 작성한다.
• installer, registry write, 외부 dependency 다운로드와 public ABI 약속은 범위 밖이다.

Step 2 — install-tree-smoke-test

• source/build tree를 참조하지 않는 consumer configure/link test를 만든다.
• 설치된 CLI의 --version, example solve와 생성 HDF5 open을 검증한다.
• 개발 PATH의 fesa.exe나 source include fallback으로 결함을 숨기지 않는다.

Step 3 — phase1-scale-benchmark

• 약 100,000 DOF Beam chain에서 generation/parsing, assembly, PARDISO solve, recovery와 HDF5 write 시간을 분리해 측정한다.
• 재현 가능한 Windows memory metric, thread/solver 설정과 실제 DOF 수를 기록한다.
• finite result, 평형과 정상 종료는 검사하되 임의 시간·speedup 기준은 만들지 않는다.

Step 4 — release-evidence-gate

• Debug와 Release configure/build/test를 새로 실행한다.
• test count가 0이 아닌지 확인한다.
• Harness pytest, reference, determinism, HDF5 inspection, install-tree smoke test와 scale benchmark 증거를 checklist ID에 연결한다.
• 모든 수용 조건에 현재 실행 증거가 있을 때만 Step과 Phase를 completed로 바꾼다.
• 실패나 미실행 항목이 있으면 정확한 blocker를 남기고 release 완료를 선언하지 않는다.

6. 유지해야 할 경계

• C++20, Visual Studio 2026 MSVC v145와 Windows x64 기준을 유지한다.
• core, model, fem, elements에 Abaqus, MKL, TBB 또는 HDF5 API를 노출하지 않는다.
• solver semantic model과 result contract에 installer 또는 serialization 전용 타입을 추가하지 않는다.
• dependency는 개발 환경에 사전 설치된 버전을 사용하며 package 중 다운로드하지 않는다.
• install tree는 source/build tree의 절대경로에 의존하지 않아야 한다.
• Debug와 Release artifact/runtime을 혼합하지 않는다.
• FESA는 단위 변환을 수행하지 않는다.
• performance 수치를 correctness gate로 바꾸지 않는다.
• stress를 Abaqus-qualified로 표현하지 않는다.
• 테스트를 disable하거나 제외해 release evidence를 만들지 않는다.
• 사용자가 명시적으로 요청하지 않은 phase 실행에서는 --push를 사용하지 않는다.

7. 검증 기준선과 개발환경

7.1 마지막 확인 결과

2026-08-03의 beam reference qualification 완료 및 dev 병합 후 다음을 확인했다.

• cmake --build --preset windows-debug: 성공, 새 MSVC warning 없음
• ctest --preset windows-debug --output-on-failure: 68/68 통과
• uv run --with pytest python -m pytest -v -rs: 20/20 통과
• thread {1,2,16}에서 10회 반복한 조립/해석 결과: bitwise 동일

이 수치는 새 세션이 유지해야 할 Debug baseline이다. Release와 install-tree 결과로 확대 해석하지 않는다.

7.2 Package 설정

새 PowerShell 세션에서 configure 전에 현재 설치 위치를 확인한다. tracked preset이나 CMake 파일에 사용자별 절대경로를 넣지 않는다.

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

네 경로가 모두 유효한 같은 셸에서 preset을 실행한다. cache가 없거나 package 위치가 변경됐을 때만 --fresh configure를 사용한다.

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

Release evidence는 internal-release Step에서 새로 생성한다.

cmake --preset windows-release
cmake --build --preset windows-release
ctest --preset windows-release --output-on-failure

8. Harness 주의사항

표준 실행 명령은 다음과 같다.

python scripts/execute.py internal-release

이전 beam reference phase에서 Harness child가 WindowsApps PowerShell을 시작하지 못해 CreateProcessAsUserW 오류가 반복됐다. 동일 저장소와 preset에서 직접 실행한 수용 명령은 성공했고, stepN-output.json에는 child 환경 blocker와 직접 실행 증거를 구분해 기록했다.

새 세션에서는 다음 원칙을 지킨다.

1. 먼저 표준 Harness 실행을 시도한다.
2. 같은 child shell 오류가 발생하면 중복 executor를 시작하지 말고 남은 process를 확인한다.
3. 직접 실행한 명령과 Harness 실행 결과를 혼동하지 않고 metadata에 사실대로 적는다.
4. 사용자 profile이나 drive root를 --codex-add-dir로 허용하지 않는다.
5. global Codex 설정을 임시 변경했다면 원래 값을 기록하고 종료 즉시 복원·재확인한다.
6. 사용자가 push를 명시하지 않은 phase 실행에는 --push를 추가하지 않는다.

9. 새 세션 시작 순서

1. AGENTS.md와 이 문서를 읽는다.
2. docs/PRD.md 8절, docs/VALIDATION.md, phases/internal-release/index.json과 Step 0~4를 읽는다.
3. Git 상태와 dev == origin/dev를 확인한다.
4. 4.4절의 Step 0/4 reference 범위 문구를 최신 계약에 맞춘다.
5. Debug baseline을 새로 실행한다.
6. Step 0의 release 문서와 checklist 요구조건을 먼저 테스트 가능한 형태로 고정한다.
7. 다음 명령으로 Phase를 실행한다.

python scripts/execute.py internal-release

각 Step에서는 실패하는 검사 또는 미충족 evidence를 먼저 확인하고, 최소 변경으로 수용 조건을 만족시킨 뒤 focused test와 전체 test를 실행한다. Step output과 phase metadata는 실제 명령 결과를 그대로 반영한다.

10. internal-release 완료 조건

• phases/internal-release/index.json의 Step 0~4가 모두 completed
• phases/index.json의 internal-release가 completed
• PRD 8절의 모든 기준이 고유 checklist ID와 실제 증거에 연결됨
• Debug/Release build에 새 MSVC warning이 없음
• Debug/Release CTest와 Harness pytest가 0개가 아닌 상태로 모두 통과
• cmake --install 결과에 요구 binary/library/header/document/example/runtime inventory가 포함됨
• source/build tree를 숨긴 install consumer와 CLI/HDF5 smoke test 통과
• 약 100,000 DOF benchmark의 correctness, stage time, memory와 환경 기록 완료
• Gate A PASS와 Gate B EVALUABLE의 의미 및 Abaqus stress 제한을 release 문서가 정확히 유지함
• 실패하거나 미실행인 증거가 없는 경우에만 내부 배포 완료 선언

새 세션의 권장 첫 요청은 다음과 같다.

docs/HANDOFF.md와 internal-release의 index/step0~4를 읽고 현재 dev baseline과 beam reference 검증 범위를 확인해주세요. Step 0과 Step 4의 stale reference 문구를 PRD/VALIDATION에 맞춘 뒤 internal-release Phase를 시작해주세요.