docs: organize project guidance and module contracts

src/fesa/AGENTS.md

@@ -0,0 +1,14 @@
+# Solver 구현과 target 조합
+
+이 영역은 fesa_solver와 fesa_cli의 production 구현을 소유한다. Public interface와 vendor
+resource 사이의 구현 책임을 유지하며 테스트 실행기나 문서 workflow를 solver에 연결하지 않는다.
+
+- CMake target에 새 source와 필요한 private dependency를 명시한다. Link 성공뿐 아니라
+  Windows runtime staging의 영향을 확인한다.
+- Public consumer가 implementation header를 include하도록 경로를 공개하지 않는다.
+  MKL·TBB·HDF5·Win32는 private adapter 뒤에 둔다.
+- Core 기능 추가는 input 의미 → model → equation → solve → recovery → output의
+  실제 연결과 필요한 검증 범위를 함께 고려한다. Kernel 존재만으로 공개 지원을 선언하지 않는다.
+- /W4와 /WX가 적용되는 MSVC x64 Debug 기준을 유지하고 새 warning을 추가하지 않는다.
+- 하위 영역 간 소유권을 바꾸는 수정은 기존 수식·source identity·상태 수명에 대한
+  영향을 먼저 검토한다. 무관한 모듈을 함께 refactor하지 않는다.

src/fesa/analysis/AGENTS.md

@@ -0,0 +1,16 @@
+# Procedure와 상태 수명
+
+Analysis는 준비된 Domain을 procedure별로 실행하고 equation·backend·trial·commit·recovery를
+조정한다. Concrete HDF5 layout이나 vendor handle을 공개 state에 저장하지 않는다.
+
+- AnalysisModel은 Domain의 non-owning view다. State에는 해당 procedure가 실제 사용하는
+  mutable 해와 recovery만 둔다. 새 procedure를 static lifecycle의 조건문으로 누적하지 않는다.
+- Linear static은 Kff factorization 뒤 load assembly, effective RHS, full 해와 residual 복구를
+  수행한다. Empty free를 singular로 오인하지 않는다.
+- Nonlinear/HHT는 trial을 committed state/history와 분리한다. 수렴·finite·recovery 검증을
+  모두 마친 candidate만 반영하고 실패한 trial의 일부 값이 history에 남지 않게 한다.
+- HHT physical a, auxiliary A, 공간 angular acceleration을 구분하고 consistent kinetic
+  mass·analytic null·부분구속 의미를 유지한다. 시간수렴 실패를 기준 완화로 숨기지 않는다.
+- Frequency reduction은 null/finite 공간과 공개 mode 수·내부 검증 수를 구분한다.
+- 초기화, nonzero BC, all-constrained, 증분·반복 종료 경계, 실패 보존, temporal convergence,
+  반복 결정론과 backend failure를 검증한다. 한 reference의 U 일치로 모든 physics를 통과시키지 않는다.

src/fesa/app/AGENTS.md

@@ -0,0 +1,15 @@
+# CLI와 실행 조합
+
+App은 입력 인자·결과 경로·output lease·실행 객체 조합·진단과 exit 변환을 소유한다.
+해석식·수렴 기준·HDF5 dataset 정의를 이 영역에서 결정하지 않는다.
+
+- 단일 .inp 경로에서 결과와 로그의 lexical sibling을 만든다. Canonical 경로로 바꾸거나
+  --output을 우회 수용하지 않는다.
+- Lease 획득 전 공개 파일을 truncate하지 않는다. 같은 output pair의 충돌과 실패 시
+  기존 final HDF5 보존을 유지한다.
+- 준비된 입력은 한 번 mapping한 Domain으로 실행한다. Procedure마다 다시 파싱하거나
+  concrete state를 static 결과로 위장하지 않는다.
+- 성공 outcome과 로그 close를 확인한 뒤 해당 결과 writer를 호출한다. 로그 오류를
+  무시하고 정상 결과 저장으로 진행하지 않는다.
+- Usage·input·model·solver·output 오류의 외부 분류를 보존한다. Argument 개수, 잘못된
+  확장자, 상대 경로, busy output, 기존 결과가 있는 실패와 성공 finalize를 검증한다.

src/fesa/assembly/AGENTS.md

@@ -0,0 +1,13 @@
+# 결정적인 sparse·하중 조립
+
+Assembly는 element/load의 local contribution을 global matrix/vector로 누적한다.
+Equation 번호와 pattern의 owner는 DofManager이며 worker가 pattern을 변경하지 않는다.
+
+- Worker는 element/index-owned buffer만 쓰고 join 뒤 stable COO ordering과 고정된
+  reduction으로 합산한다. Global CSR에 직접 병렬 더하기를 하지 않는다.
+- Full-space stiffness·내력·외력·pressure tangent의 scatter와 부호를 유지한다.
+  Free 성분만 조립해 constrained reaction의 근거를 잃지 않는다.
+- 여러 element가 같은 DOF에 기여하는 순서는 thread scheduling에 의존하지 않는다.
+  Failure diagnostic도 발견 시각이 아니라 지정된 순서로 선택한다.
+- Serial/parallel 일치, shared node 누적, 중복 COO, invalid contribution, empty partition,
+  pressure 합력·모멘트와 tangent를 검증한다.

src/fesa/constraints/AGENTS.md

@@ -0,0 +1,12 @@
+# 지정값과 partition 정책
+
+Constraints는 prescribed displacement와 equation에 적용하는 essential constraint 정책을
+소유한다. 새 물리 DOF·source target 범위·reaction 의미를 단독으로 변경하지 않는다.
+
+- Elimination은 full matrix의 free/constrained coupling을 유지한다. Nonzero prescribed
+  값의 기여를 RHS에서 빠뜨리거나 constrained load를 버리지 않는다.
+- 해 복구 후 full vector에서 지정값을 유지한다. Physical reaction과 free residual은
+  같은 조립 방정식의 서로 다른 성분이며 서로 대체하지 않는다.
+- 빈 free system은 별도로 유효하게 처리하고 artificial penalty로 풀지 않는다.
+- Homogeneous·nonzero BC, 충돌한 지정값, all-constrained, free/constrained permutation과
+  full residual 복구를 검증한다. 새 enforcement 방식은 공개 결과 영향까지 정의한다.

src/fesa/core/AGENTS.md

@@ -0,0 +1,13 @@
+# 공통 identity와 진단
+
+Core는 source identity·ASCII token 처리와 Status/Diagnostic의 공통 의미를 소유한다.
+Procedure별 keyword 허용 여부나 물리식을 이 영역의 공통 default로 넣지 않는다.
+
+- Raw source spelling과 canonical lookup 값을 구분한다. ASCII case 처리를 locale
+  의존 변환으로 바꾸지 않는다.
+- Source 위치·instance·label과 내부 index를 혼용하지 않는다. Diagnostic sorting은
+  실행 thread나 hash iteration 순서와 독립적이어야 한다.
+- Expected failure를 성공·빈 결과로 치환하지 않는다. Backend 예외를 통과시키는 새 경로를
+  만들 때 공개 실패 범위와 분류를 먼저 검토한다.
+- Label 경계·invalid token·대소문자·빈 source 필드·동일 진단의 반복 정렬을 검증한다.
+  의미가 다른 사용자 오류를 메시지 하나로 합쳐 identity를 잃지 않는다.

src/fesa/elements/AGENTS.md

@@ -0,0 +1,16 @@
+# 요소 local 계산
+
+Elements는 Euler beam·MITC4 shell의 local 강성·내력·관성·복구용 응답을 소유한다.
+Global equation 번호, 공유 sparse write와 파일 저장은 소유하지 않는다.
+
+- Local node/DOF 순서, 축·회전 chart·director와 부호를 정식화와 일치시킨다.
+  Source S4/S4R 이름이 FESA 적분·stabilization 선택을 바꾸지 않는다.
+- Physical 에너지와 drilling 안정화 항을 분리한다. 질량 영공간에 임의 회전관성을
+  추가하거나 고유치와 HHT의 질량 계약을 통합하지 않는다.
+- Trial response는 실패 시 기존 유효 상태를 보존한다. 비선형 접선·관성·convective 항은
+  동일 kinematics에서 유도하고 대칭이라고 가정해 항을 버리지 않는다.
+- 새 수식·적분·상태 갱신은 독립 numerical review와 analytical/invariant 검사 대상이다.
+  Rigid motion, patch, tangent 대조, 에너지, 두께 scaling, 질량 영모드·양성 및 좌표변환을
+  변경에 맞게 검증한다.
+- End action·단면력·응력의 location과 부호가 다르면 같은 recovery 함수로 강제하지 않는다.
+  Local kernel 완료를 Abaqus 입력이나 CLI 노출 완료로 확대하지 않는다.

src/fesa/fem/AGENTS.md

@@ -0,0 +1,13 @@
+# DOF와 equation 구성
+
+DofManager가 물리 DOF, full/free/constrained mapping, equation 번호, scatter와 sparse
+pattern을 소유한다. 이 정보를 Node·Element·개별 solver에 분산 저장하지 않는다.
+
+- Source node identity와 equation index를 구분하고 numbering·row ordering을 결정적으로 만든다.
+- Partition은 전체 DOF를 중복·누락 없이 덮어야 한다. Prescribed 값과 free 해 복구가 같은
+  mapping을 사용해야 하며 partial rotation constraint를 full clamp로 바꾸지 않는다.
+- 모든 DOF가 constrained인 유효한 모델의 0차원 free system을 허용한다. Empty free와
+  잘못된 topology·singular free matrix는 다른 경우다.
+- Validation은 임의 fallback으로 잘못된 scatter를 건너뛰지 않는다.
+- Renumbering, shared nodes, mixed free/constrained, all-constrained, invalid scatter와
+  serial/parallel 경로의 동일 sparse structure를 검증한다.

src/fesa/io/abaqus/AGENTS.md

@@ -0,0 +1,17 @@
+# Abaqus 입력 adapter
+
+이 영역은 physical source·syntax·scope·default를 검증된 Domain 정의로 mapping한다.
+Abaqus 전체 호환성이나 내부 요소·해법 동등성을 목표로 하지 않는다.
+
+- Raw text/빈 field/source line과 canonical lookup을 구별한다. ASCII case 처리,
+  keyword continuation, physical line 제한과 duplicate parameter 거부를 유지한다.
+- 지원 여부는 procedure별 allowlist로 판단한다. 무해한 출력 요청의 no-op 예외를
+  model-affecting keyword로 확대하지 않는다. INCLUDE를 자동으로 열지 않는다.
+- Instance·label·set·section/material target은 결정적으로 해소한다. 모호한 이름을
+  첫 일치값으로 선택하거나 missing 물성을 default로 채우지 않는다.
+- S4/S4R source 표기를 보존하되 FESA 내부 적분 선택값으로 사용하지 않는다.
+  Source step 이름과 canonical result storage 이름도 구분한다.
+- Procedure 선택 후 density·BC·하중·출력 요청의 조합을 검사한다. Static의 관대한 no-op을
+  HHT/eigen에 복사하지 않는다.
+- Valid minimal 입력과 각 keyword의 위치·arity·range·unknown parameter·중복·nonfinite·
+  cross-instance·여러 step 실패를 검증한다. Parser 수용만으로 새 기능 완료를 선언하지 않는다.

src/fesa/io/hdf5/AGENTS.md

@@ -0,0 +1,15 @@
+# HDF5 출력 adapter
+
+이 영역은 검증된 state를 영속 schema로 기록하고 readback·close·최종 교체를 수행한다.
+새 물리량의 정의와 acceptance 기준을 writer 편의로 바꾸지 않는다.
+
+- Procedure와 version을 함께 식별한다. Eigen의 additive discriminator와 static/dynamic
+  frame 의미를 구분하고 기존 필수 dataset을 optional로 바꾸지 않는다.
+- Fixed-width little-endian 수치, UTF-8 문자열, compound field 이름·shape·component·unit·
+  coordinate/location과 source identity를 보존한다. C++ padding을 file contract로 쓰지 않는다.
+- 임시 candidate에 기록·self-check·close한 뒤 final을 교체한다. 실패한 frame·write·close가
+  기존 final HDF5를 손상시키지 않아야 한다. State commit과 file finalize는 별개다.
+- Source step 이름을 path로 직접 넣거나 node row를 source label로 해석하지 않는다.
+  Auxiliary acceleration·generalized force를 physical 결과 이름으로 바꾸지 않는다.
+- Mandatory field/attribute·shape·dtype·ordering·nonfinite·version 거부, readback과 각
+  failure boundary를 검증한다. Reference artifact를 writer 결과에 맞춰 수정하지 않는다.

src/fesa/loads/AGENTS.md

@@ -0,0 +1,12 @@
+# 하중 의미와 local contribution
+
+Loads는 concentrated nodal load와 shell surface pressure의 의미·configuration·local
+contribution을 소유한다. Source 이름의 해석은 mapping 경계에서, global 누적은 assembly에서 한다.
+
+- Global dead load와 현재 geometry를 따르는 압력을 구분한다. SPOS/SNEG와 압력 부호를
+  element normal 관례에 맞추며 실패한 geometry를 normal 뒤집기로 숨기지 않는다.
+- Full-space 외력과 비선형 load tangent의 부호·미분 대상을 유지한다. Constrained DOF의
+  하중을 미리 제거하면 반력 의미가 달라지므로 free RHS만 반환하지 않는다.
+- 동일 target 하중은 안정된 source 순서로 합산하며 서로 다른 facet를 node 평균으로 합치지 않는다.
+- 면적·법선·합력·모멘트와 tangent를 독립 대조하고 회전·반전 side·여러 facet·중복 입력을
+  검증한다. 정적 pressure 지원을 dynamic·thermal 입력까지 확대하지 않는다.

src/fesa/materials/AGENTS.md

@@ -0,0 +1,13 @@
+# 재료 구성 관계
+
+Materials는 현재 승인된 물성 capability와 구성 응답을 소유한다. Topology, DOF,
+element state와 전체 해석 수렴은 이 영역의 책임이 아니다.
+
+- Isotropic elastic parameter의 finite·range와 units를 생성 경계에서 유지한다.
+  잘못된 값에 epsilon을 더하거나 clamp하지 않는다.
+- Density·thermal·비탄성 등 서로 다른 의미를 기존 base의 미사용 field로 누적하지 않는다.
+  실제 사용되는 capability와 승인된 procedure만 연결한다.
+- Material은 analysis state를 임의 소유하지 않는다. 향후 history-dependent 재료는
+  trial/commit과 실패 보존을 별도로 정의한다.
+- Constitutive 응답·대칭성·경계값·invalid 조합을 독립적인 식과 대조한다. Parser에서
+  읽을 수 있다는 이유로 모든 procedure가 해당 물성을 지원한다고 판단하지 않는다.

src/fesa/math/AGENTS.md

@@ -0,0 +1,12 @@
+# 수치 값과 storage
+
+Math는 backend-neutral Vector·Matrix·SparseMatrix와 private dense-BLAS 연산을 소유한다.
+Source identity나 모델의 물리·constraint 의미는 저장하지 않는다.
+
+- Public 타입에 MKL pointer·integer·handle을 노출하지 않는다. Size 변환과 allocation
+  overflow는 adapter 경계에서 검증하고 잘못된 차원을 truncate하지 않는다.
+- Dense와 sparse storage의 의미를 하나의 상속 구조로 억지로 합치지 않는다.
+- Copy·alias·lifetime와 operation/reduction 순서는 결과 계약이다. Refactoring으로
+  비결정적인 합산이나 silent zero clamp를 도입하지 않는다.
+- 0차원 연산, shape mismatch, sparse 중복/정렬, copy/move, 비유한 입력과 backend 경계의
+  크기 조건을 검증한다. 물리 잔차 tolerance를 이 영역에서 새로 선택하지 않는다.

src/fesa/model/AGENTS.md

@@ -0,0 +1,14 @@
+# 모델 정의와 source target
+
+Model은 Domain의 전체 정의, source target resolution과 초기 shell geometry를 소유한다.
+Mutable 해·equation 번호·factorization resource를 node나 element 정의에 저장하지 않는다.
+
+- Domain은 view보다 오래 살아야 한다. Mapping 이후의 정의를 실행 편의를 위해 복사·변형해
+  서로 다른 원본처럼 유지하지 않는다.
+- SourceTargetResolver의 instance/set 범위를 보존한다. 같은 숫자 label을 다른 instance와
+  합치거나 모호한 이름을 첫 번째 항목으로 선택하지 않는다.
+- Section과 material의 연결은 유일하게 검증한다. Missing property를 기본 물성으로 채우지 않는다.
+- Shell director/frame은 승인된 geometry 의미를 따른다. 잘못된 연결·방향·degenerate
+  geometry를 clamp 또는 averaging으로 숨기지 않는다.
+- Declaration order, 재배열된 label, 여러 instance, 중복/모호한 set, invalid geometry와
+  non-owning view의 수명 경계를 검증한다.

src/fesa/properties/AGENTS.md

@@ -0,0 +1,12 @@
+# 요소 단면과 property
+
+이 영역은 beam general section과 shell section의 물리적 데이터 및 재료 연결을 소유한다.
+Material 구성식이나 global assembly, 실행 중 solution state는 소유하지 않는다.
+
+- 면적·두께·단면 관성·축의 units와 유효 조건을 보존한다. 값이 없거나 다른 element와
+  호환되지 않으면 structured failure로 처리하고 비슷한 section으로 대체하지 않는다.
+- Centered homogeneous shell과 beam의 단면 위치 의미를 구분한다. Source optional
+  integration-point 필드를 내부 적분법 선택값으로 재해석하지 않는다.
+- Property identity는 source/element 연결과 recovery까지 추적 가능해야 한다.
+- 생성·invalid finite/range·element/material compatibility와 두께 변화의 결과 차원을
+  검증한다. 새로운 section 의미는 kernel만 추가하지 말고 입력과 결과까지 계약한다.

src/fesa/results/AGENTS.md

@@ -0,0 +1,14 @@
+# 물리 결과 복구와 candidate commit
+
+Results는 backend-neutral 결과 record와 위치·좌표·부호가 명확한 recovery를 소유한다.
+HDF5 layout이나 reference 데이터를 맞추기 위한 보정은 하지 않는다.
+
+- Beam end action과 positive-local-x section resultant, shell generalized result와 stress를
+  구별한다. 다른 endpoint·Gauss·section 위치를 평균해 identity를 없애지 않는다.
+- Reaction은 해당 procedure의 full residual에서 얻는다. Free 성분은 residual evidence이며
+  constrained reaction과 같은 외부 비교로 섞지 않는다.
+- Physical strain energy와 drilling energy, generalized moment와 spatial moment를 구분한다.
+  Shell bending resultant의 두께 세제곱 계수를 막력의 두께 계수로 치환하지 않는다.
+- 전체 recovery candidate의 finite·identity·balance 검증 뒤 state에 반영한다.
+- Analytical recovery, thickness scaling, 원점·좌표변환, force/moment balance, failure
+  preservation와 row ordering을 검증한다. Displacement 일치만으로 recovery를 승인하지 않는다.

src/fesa/solvers/eigen/AGENTS.md

@@ -0,0 +1,13 @@
+# 고유치 backend
+
+이 영역은 실제 MKL FEAST 호출, interval/count/solve 제어와 backend evidence를 소유한다.
+Input의 LANCZOS 표기를 실제 내부 알고리즘 동등성으로 해석하지 않는다.
+
+- 승인된 count·solve 제한과 spectral enclosure를 보존한다. 실패를 임의 range 확대나
+  다른 eigen solver로 조용히 대체하지 않는다.
+- Mass null을 artificial inertia로 제거하지 않는다. Finite-space 구성과 공개 N개 모드,
+  전체 c개 내부 검증의 의미를 유지한다.
+- Vendor workspace·integer 변환·resource는 private다. 작은 음수 eigenvalue를 abs 또는
+  clamp로 숨기지 않고 raw 분류와 frequency 생성의 차이를 유지한다.
+- 독립 residual·정규화·직교성, repeated/cluster modes, count 경계·실패, deterministic
+  ordering과 source modal identity를 검증한다. 외부 mode shape 비교가 자동 필수는 아니다.

src/fesa/solvers/linear/AGENTS.md

@@ -0,0 +1,13 @@
+# 선형계 backend
+
+이 영역은 PARDISO 기반 factorization·solve와 tangent solver resource를 소유한다.
+Model 수정, constraint 추가와 물성 변경은 solver 실패의 대안이 아니다.
+
+- Positive-definite와 tangent matrix의 성질·index 형식을 구별한다. Backend 편의를 위해
+  비대칭 항을 버리거나 singular matrix에 임의 diagonal을 더하지 않는다.
+- Factorization 수명, 다중 RHS·반복 solve와 해제 경로를 adapter 내부에 격리한다.
+  Vendor exception·상태를 public Status/Result로 변환한다.
+- 실패 뒤 이전 factorization을 잘못 재사용하거나 출력 vector를 부분적으로 성공 상태로
+  남기지 않는다. Empty free 처리의 caller/backend 계약을 유지한다.
+- 알려진 해, residual, 잘못된 matrix, failure/reuse, size 변환과 resource 정리를 검증한다.
+  해가 finite인 것만으로 FEM 평형을 통과했다고 보고하지 않는다.