docs: organize project guidance and module contracts

docs/engineering-notes.md

@@ -0,0 +1,72 @@
+# 수치 구현과 검증에서 주의할 점
+
+## 실행 성공과 기능 완료의 차이
+
+HHT 원본 모델의 변위 비교는 통과 기록이 있지만 실제 shell의 두 시간수렴 사례는
+미해결이다. 따라서 외부 변위가 맞는다는 이유로 가속도 복구·시간수렴·physics 완료를
+추론하면 안 된다. 변경 후에는 동일한 dt refinement에서 변위·속도·물리 가속도의 차수를
+각각 확인해야 하며 auxiliary acceleration의 결과를 물리 가속도로 대신하지 않는다.
+
+과거 I/O 문서의 `implementation-pending` 같은 문구는 그 문서가 작성된 시점의 상태일 수
+있다. 현재 코드는 dynamic/eigen state와 writer를 포함한다. 코드 존재, 작성 당시 계획,
+후속 실행 보고서를 구분하고 날짜가 오래된 머리말 하나로 전체 기능 상태를 결정하지 않는다.
+
+## 단면력과 회전
+
+Shell 굽힘 모멘트 복구에는 두께의 세제곱 계수 `M=t^3 C kappa/12`가 들어간다.
+막력과 같은 두께 계수로 처리하면 displacement가 맞아도 section resultant가 틀릴 수 있다.
+복구식을 바꿀 때 두께를 독립적으로 바꾸는 사례와 HDF5 readback을 함께 대조한다.
+
+비선형 shell의 rotation-vector generalized moment는 spatial moment와 다르다. Chart에
+대한 일의 짝을 유지해야 하므로 성분 이름만 바꿔 공개 reaction으로 내보내지 않는다.
+자세 변화가 큰 사례와 원점 이동 시 moment balance를 확인한다.
+
+Beam section resultant는 요소 endpoint identity로 대응한다. 같은 절점에 모인 여러
+endpoint 값을 node 평균으로 줄이면 end action 부호 또는 station 불일치를 숨긴다.
+Instance·element·endpoint node·component를 함께 비교해야 한다.
+
+## 질량·영공간과 source 옵션
+
+고유치의 derived lumped mass와 HHT의 consistent kinetic mass는 승인 목적이 다르다.
+두 절차가 같은 shell을 쓴다는 이유로 질량 구현을 한 가지로 치환하지 않는다. 질량
+영공간이 있으면 analytic null과 free 공간의 교집합을 확인하고 임의 drilling inertia를
+더하지 않는다. 부분 회전 구속을 full clamp로 바꾸는 것도 같은 모델이 아니다.
+
+Source `S4R`나 shell section의 integration-point 필드는 FESA의 적분법 선택 스위치가
+아니다. Source 보존·허용 문법과 실제 numerical integration을 별도로 검증한다.
+
+## 열해석 계획에서 혼동하기 쉬운 위치
+
+온도점 5개의 DOF 11은 아랫면이며 중앙면은 DOF 13이다. 열해석 제안의 54개 직접
+적분점과 24개 flux trace는 서로 다른 목적의 위치다. 두 구간 이차 보간의 중앙면에서는
+두께 미분의 양쪽 trace가 다를 수 있어 평균하지 않는다. 이 수치 방법은 아직 채택 대기다.
+
+열전달 반력에는 열용량에 의한 저장률이 포함된다. 전도 flux만으로 반력 열률을 정의하면
+transient 에너지 수지가 달라진다. 첫 증분에서 지정 온도가 변하는 경우에는 이전 constrained
+온도의 용량 결합 항도 필요하므로 초기값을 조용히 projection하지 않는다.
+
+열 reference의 NT11에는 음수가 있다. 모든 음수를 roundoff라고 가정하거나 clamp하지
+않고 원본 identity와 승인된 비교 기준으로 다룬다. 현재 CSV의 한 시점 온도만으로 flux,
+반력, 다른 두께 온도점 또는 전체 시간수렴을 검증했다고 주장하지 않는다.
+
+## 실행 환경과 결과 파일
+
+Preset 파일이 존재해도 Python 실행기가 자동 선택하지 않는다. 개인 설정에서
+`configurePreset`, `buildPreset`, `testPreset`, `binaryDir`를 함께 맞춰야 다른 build tree의
+테스트를 읽는 실수를 피할 수 있다. CTest discovery 결과가 비거나 다른 compiler가
+선택되면 실행 실패로 다룬다.
+
+MSVC link 성공 뒤 실행 시 DLL을 못 찾는다면 dependency runtime staging을 확인한다.
+개발자 PATH에 우연히 있던 DLL로 성공한 것을 배포 환경 검증으로 보고하지 않는다.
+Python suite는 CTest와 별개이므로 runner의 성공에 포함시켜 보고하지 않는다.
+
+CLI 결과 경로는 입력의 lexical parent다. Symlink나 junction을 canonical 경로로
+치환하면 사용자가 지정한 output 위치 의미가 바뀐다. Output lease와 atomic replace의
+검증에서는 기존 final HDF5뿐 아니라 로그·임시 파일의 서로 다른 실패 수명을 확인한다.
+
+## 과거 개발 절차와 검사
+
+일부 Python 검사는 삭제된 coordinator·planning·correction profile과 고정 단계 표를
+기대한다. 현재 agent inventory 및 인자 없는 실행기와 맞지 않는 정적 근거가 있다.
+이전 검사를 만족시키기 위해 폐기된 profile·phase·hook을 복원하지 않는다. 현행 절차를
+확인한 뒤 별도 테스트 변경 작업으로 정리하고 실제 실행 결과를 기록한다.