modify documents

docs/project-plan/SOLVER_AGENT_DESIGN.md

@@ -0,0 +1,365 @@
+# 구조해석 솔버 개발 Agent 구성안
+
+## 목적
+이 문서는 Abaqus, Nastran과 같은 유한요소법 기반 구조해석 솔버를 개발하기 위한 AI Agent 운영 구성을 정의한다.
+
+이번 구성안은 ALL-FEM 논문의 구조를 확장하거나 재사용하는 계획이 아니다. 논문은 Agent 설계를 위한 참고 자료로만 사용하며, 본 프로젝트는 C++/MSVC 기반 독립 솔버 개발 워크플로우를 따른다.
+
+## 설계 원칙
+- 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
+- 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
+- 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
+- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `references/`에 저장된 입력 파일과 레퍼런스 CSV 결과를 검증 기준으로 사용한다.
+- 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
+- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
+
+## 전체 Agent 구성
+
+### Coordinator Agent
+전체 개발 흐름을 관리하는 상위 조정 Agent이다.
+
+책임:
+- 기능 개발 요청을 단계별 작업으로 분해한다.
+- 각 Agent의 산출물을 연결하고 누락된 결정을 추적한다.
+- 요구조건, 정식화, 테스트, 구현, 검증, 배포 단계의 진행 상태를 관리한다.
+- 실패 시 어떤 Agent로 되돌릴지 결정한다.
+
+주요 산출물:
+- 기능별 개발 계획
+- 단계별 승인 상태
+- 실패 원인과 재작업 지시
+
+### Requirement Agent
+솔버 기능 요구조건을 정의하는 Agent이다.
+
+책임:
+- 해석 기능의 범위, 입력, 출력, 제약조건을 정의한다.
+- 대상 요소, 재료 모델, 경계조건, 하중 조건, 해석 타입을 명확히 한다.
+- 검증해야 할 물리량과 tolerance 기준을 정한다.
+
+주요 산출물:
+- 기능 요구조건 문서
+- acceptance criteria
+- 검증 물리량 목록
+
+예시 검증 물리량:
+- 절점 변위
+- 반력
+- 요소 내력
+- 응력
+- 변형률
+- 에너지 또는 잔차 기준
+
+### Research Agent
+책, 논문, 매뉴얼, 공개 benchmark를 조사하는 Agent이다.
+
+책임:
+- 유한요소 정식화에 필요한 이론 자료를 수집한다.
+- 요소별 benchmark와 patch test 사례를 찾는다.
+- Abaqus/Nastran 결과와 비교할 수 있는 공개 예제 또는 문헌 해를 조사한다.
+- 자료의 신뢰도와 적용 범위를 평가한다.
+
+주요 산출물:
+- 연구자료 요약
+- 공식, 가정, 한계 정리
+- benchmark 후보 목록
+
+### Formulation Agent
+코드 구현을 위한 유한요소 정식화를 작성하는 Agent이다.
+
+책임:
+- 약형, 형상함수, B matrix, constitutive matrix, 수치적분, 요소 강성 행렬을 정의한다.
+- 자유도 배치, 좌표계, 단위계, 부호 규약을 명확히 한다.
+- 선형/비선형, 정적/동적, small/large deformation 여부를 구분한다.
+- 구현 가능한 알고리즘 형태로 정식화를 정리한다.
+
+주요 산출물:
+- 요소별 정식화 문서
+- 알고리즘 의사코드
+- 수치적분 규칙
+- edge case와 singular case 목록
+
+### Numerical Review Agent
+정식화와 수치 알고리즘을 독립 검토하는 Agent이다.
+
+책임:
+- 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
+- rigid body mode, patch test, symmetry, positive definiteness 등 기본 수치 조건을 확인한다.
+- locking, hourglass mode, ill-conditioning 같은 위험을 식별한다.
+- 구현 전 정식화 오류를 줄인다.
+
+주요 산출물:
+- 정식화 리뷰 결과
+- 수치 위험 목록
+- 추가 테스트 요구사항
+
+### I/O Definition Agent
+솔버 입력과 출력 데이터 구조를 정의하는 Agent이다.
+
+책임:
+- mesh, node, element, material, section, boundary condition, load, step 입력 형식을 정의한다.
+- 출력 CSV 또는 result file schema를 정의한다.
+- Abaqus input file과 내부 입력 모델 사이의 대응 관계를 정리한다.
+- 결과 비교를 위해 레퍼런스 CSV와 구현 솔버 출력의 컬럼 규약을 맞춘다.
+
+주요 산출물:
+- 입력 데이터 schema
+- 출력 데이터 schema
+- 결과 비교용 CSV schema
+- 단위와 좌표계 규약
+
+### Reference Model Agent
+TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.
+
+책임:
+- 개발 대상 기능을 검증할 최소 모델, benchmark 모델, 회귀 모델을 설계한다.
+- `references/`에 보관할 Abaqus input file과 Abaqus 결과 CSV 요구사항을 정의한다.
+- 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다.
+- 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.
+
+중요 제약:
+- Agent는 Abaqus를 직접 실행하지 않는다.
+- Abaqus 해석 결과는 사람이 생성하거나 별도 승인된 절차로 생성해 `references/`에 저장한다.
+- Agent는 저장된 reference artifact만 사용해 비교한다.
+
+권장 reference 구조:
+```text
+references/
+  <feature-name>/
+    model.inp
+    metadata.json
+    displacements.csv
+    reactions.csv
+    element_forces.csv
+    stresses.csv
+```
+
+### Implementation Planning Agent
+코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다.
+
+책임:
+- 요구조건과 정식화를 C++ 구현 작업으로 분해한다.
+- 먼저 작성할 단위 테스트, 통합 테스트, 레퍼런스 비교 테스트를 정의한다.
+- 기존 architecture와 ownership boundary에 맞춰 변경 파일을 제한한다.
+- 구현 Agent가 따라야 할 acceptance criteria를 제공한다.
+
+주요 산출물:
+- 구현 계획
+- 테스트 우선순위
+- 변경 파일 후보
+- acceptance checklist
+
+### Implementation Agent
+C++ 코드를 구현하는 Agent이다.
+
+책임:
+- 테스트를 먼저 작성하고 실패를 확인한다.
+- 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
+- C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
+- 불필요한 일반화나 speculative abstraction을 피한다.
+
+주요 산출물:
+- C++ source/header 변경
+- 테스트 코드
+- CMake/CTest 변경
+
+### Build/Test Executor Agent
+빌드와 테스트를 실행하는 Agent이다.
+
+책임:
+- Harness validation을 실행한다.
+- MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
+- 실패 로그를 요약하고 Correction Agent에 전달한다.
+
+기본 검증 명령:
+```powershell
+python scripts/validate_workspace.py
+```
+
+검증 대상:
+- CMake configure
+- MSVC Debug build
+- CTest
+- Harness self-test
+
+### Correction Agent
+빌드, 테스트, 런타임 실패를 수정하는 Agent이다.
+
+책임:
+- 실패 로그를 원인별로 분류한다.
+- 컴파일 오류, 링크 오류, 테스트 실패, 결과 비교 실패를 구분한다.
+- 최소 수정으로 실패를 해결한다.
+- 같은 실패가 반복되면 Coordinator Agent에 차단 상태를 보고한다.
+
+주요 산출물:
+- 수정 패치
+- 실패 원인 요약
+- 재검증 요청
+
+### Reference Verification Agent
+구현 솔버 결과와 저장된 레퍼런스 결과를 비교하는 Agent이다.
+
+책임:
+- 구현 솔버 결과 CSV와 `references/`의 Abaqus CSV를 비교한다.
+- 절점 변위, 반력, 요소 내력, 응력의 tolerance 만족 여부를 평가한다.
+- absolute tolerance, relative tolerance, norm-based tolerance를 구분해 적용한다.
+- 결과 차이가 tolerance 밖이면 원인 후보를 분류한다.
+
+주요 산출물:
+- reference comparison report
+- 실패한 물리량과 위치
+- 최대 오차, 평균 오차, norm 오차
+
+### Physics Evaluation Agent
+수치 결과가 물리적으로 타당한지 검토하는 Agent이다.
+
+책임:
+- 레퍼런스와 수치적으로 비슷해도 물리적으로 이상한 결과가 있는지 확인한다.
+- 변위 방향, 반력 평형, 응력 집중, 대칭 조건, rigid body mode를 검토한다.
+- 테스트 모델이 기능을 충분히 검증하지 못하면 추가 모델을 요구한다.
+
+주요 산출물:
+- 물리 검토 결과
+- 추가 검증 모델 요구사항
+- release 가능 여부 의견
+
+### Release Agent
+기능 배포 준비를 담당하는 Agent이다.
+
+책임:
+- 요구조건, 테스트, 레퍼런스 비교, 물리 검토가 모두 통과했는지 확인한다.
+- 기능 문서와 release note를 정리한다.
+- 알려진 제한사항과 tolerance 기준을 기록한다.
+
+주요 산출물:
+- release checklist
+- 기능 문서
+- known limitations
+
+## 개발 프로세스 매핑
+
+| 개발 과정 | 담당 Agent | 필수 산출물 |
+| --- | --- | --- |
+| 1. 솔버 기능 요구조건 정의 | Requirement Agent | 요구조건, acceptance criteria |
+| 2. 연구자료 조사 | Research Agent | 자료 요약, benchmark 후보 |
+| 3. 유한요소 정식화 | Formulation Agent, Numerical Review Agent | 정식화 문서, 리뷰 결과 |
+| 4. 입출력 데이터 정의 | I/O Definition Agent | 입력/출력 schema |
+| 5. TDD 테스트모델 작성 | Reference Model Agent, Implementation Planning Agent | 테스트 모델, reference artifact 요구사항 |
+| 6. 코드 구현 | Implementation Agent | C++ 코드, 테스트 |
+| 7. 레퍼런스 결과 비교 검증 | Reference Verification Agent, Physics Evaluation Agent | 비교 리포트, 물리 검토 |
+| 8. tolerance 만족 시 완료 | Coordinator Agent | 기능 완료 승인 |
+| 9. 기능 배포 | Release Agent | release checklist, 문서 |
+
+## 표준 작업 흐름
+
+```mermaid
+flowchart TD
+  A["기능 요청"] --> B["Requirement Agent"]
+  B --> C["Research Agent"]
+  C --> D["Formulation Agent"]
+  D --> E["Numerical Review Agent"]
+  E --> F["I/O Definition Agent"]
+  F --> G["Reference Model Agent"]
+  G --> H["Implementation Planning Agent"]
+  H --> I["Implementation Agent"]
+  I --> J["Build/Test Executor Agent"]
+  J --> K{"빌드/테스트 통과?"}
+  K -- "아니오" --> L["Correction Agent"]
+  L --> I
+  K -- "예" --> M["Reference Verification Agent"]
+  M --> N{"tolerance 만족?"}
+  N -- "아니오" --> O["Physics Evaluation Agent"]
+  O --> L
+  N -- "예" --> P["Physics Evaluation Agent"]
+  P --> Q{"물리 검토 통과?"}
+  Q -- "아니오" --> L
+  Q -- "예" --> R["Release Agent"]
+```
+
+## 검증 Gate
+
+### Gate 1: 요구조건 승인
+통과 조건:
+- 대상 기능과 제외 범위가 명확하다.
+- 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
+- 레퍼런스 비교 방식이 정해져 있다.
+
+### Gate 2: 정식화 승인
+통과 조건:
+- 요소 정식화와 수치적분 규칙이 문서화되어 있다.
+- 좌표계, 자유도, 부호 규약이 명확하다.
+- Numerical Review Agent가 주요 수치 위험을 검토했다.
+
+### Gate 3: 테스트 준비 승인
+통과 조건:
+- 구현 전 실패해야 하는 테스트가 정의되어 있다.
+- `references/` artifact 요구사항이 명확하다.
+- 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다.
+
+### Gate 4: 구현 검증
+통과 조건:
+- CMake/MSVC/CTest validation이 통과한다.
+- 단위 테스트와 통합 테스트가 통과한다.
+- Harness TDD guard를 만족한다.
+
+### Gate 5: 레퍼런스 검증
+통과 조건:
+- 저장된 Abaqus CSV 결과와 구현 솔버 결과가 tolerance 안에 있다.
+- 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다.
+- 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다.
+
+### Gate 6: 배포 승인
+통과 조건:
+- 요구조건의 acceptance criteria가 모두 만족된다.
+- 문서와 release note가 준비되어 있다.
+- 남은 제한사항이 명확히 기록되어 있다.
+
+## Reference CSV 비교 기준
+
+권장 비교 방식:
+- scalar 값: absolute tolerance와 relative tolerance를 함께 적용한다.
+- vector 값: component-wise 비교와 norm 비교를 함께 기록한다.
+- stress tensor: component-wise 비교를 기본으로 하고, 필요한 경우 principal stress 또는 von Mises stress를 추가 비교한다.
+- 반력: 전체 하중 평형과 개별 구속 자유도 반력을 모두 확인한다.
+
+권장 리포트 항목:
+- model name
+- compared quantity
+- number of compared rows
+- maximum absolute error
+- maximum relative error
+- RMS error
+- worst node or element id
+- pass/fail
+
+## 반복 실패 처리
+
+반복 실패가 발생하면 Correction Agent가 무한 수정 루프를 계속하지 않는다. 다음 중 하나로 분류해 Coordinator Agent에 보고한다.
+
+- 요구조건 불명확
+- 정식화 오류 가능성
+- reference artifact 오류 가능성
+- I/O schema 불일치
+- 구현 결함
+- tolerance 기준 부적절
+- 테스트 모델이 기능을 과도하게 또는 불충분하게 검증함
+
+Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Definition, Reference Model, Implementation Agent 중 적절한 단계로 되돌린다.
+
+## 초기 적용 우선순위
+
+1. 선형 정적 해석의 최소 골격
+2. 1D truss 또는 bar element
+3. 2D plane stress/plane strain element
+4. 3D solid element
+5. material model 확장
+6. nonlinear 또는 dynamic analysis 확장
+
+각 단계는 요구조건, 정식화, 테스트모델, 구현, 레퍼런스 비교, 배포 Gate를 독립적으로 통과해야 한다.
+
+## 운영 메모
+
+- Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
+- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건을 `metadata.json`에 기록한다.
+- reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
+- 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다.

docs/project-plan/SOLVER_ARCHITECTURE_INITIAL_DISIGN.md

@@ -0,0 +1,251 @@
+# 솔버 설계 문서
+
+## 목표
+FESA는 MITC4 Shell 요소 기반 구조해석에서 시작해 비선형 정적해석, 비선형 동적해석, 열전달 및 thermal-stress coupling, 1D/3D 요소까지 확장하는 유한요소 솔버이다.
+초기 구현은 정확도와 테스트 가능성을 우선한다. 단, 대규모 모델을 목표로 하므로 자유도 관리, 희소 행렬 조립, 선형 솔버, 병렬 실행 계층은 초기부터 성능 확장이 가능하도록 분리한다.
+
+## 설계 원칙
+- Domain 객체는 입력 모델의 의미를 보존하고 가능한 한 불변에 가깝게 유지한다.
+- 해석 중 변하는 물리량과 반복 상태는 AnalysisState에 명시적으로 분리한다.
+- 요소, 재료, 하중, 경계조건, 해석 알고리즘은 런타임 다형성 기반으로 확장한다.
+- 결과는 step/frame/field/history 개념으로 저장하여 정적, 비선형, 동적, 열전달 해석을 같은 결과 모델로 다룬다.
+- 외부 라이브러리(MKL, TBB, HDF5)는 adapter 계층 뒤에 둔다.
+- Abaqus input 호환성은 파서와 factory/registry 계층에서 관리한다.
+- shell node는 6자유도이고, 단위계는 강제하지 않으며, 결과 부호는 Abaqus 규약을 따른다.
+- 경계조건은 constrained DOF 제거 방식으로 적용하고, reaction은 full vector 기준 `K_full * U_full - F_full`로 계산한다.
+- 기본 실수 precision은 `double`이고, 대규모 모델을 위해 id/index/equation numbering은 int64 기반으로 설계한다.
+- Mesh quality 진단은 1차 범위에서 제외한다. 대신 singular system 진단은 필수로 제공한다.
+
+## 디렉토리 구조
+```
+src/
+├── Analysis/        # Static, nonlinear static, dynamic, heat transfer analysis
+├── Assembly/        # 전역 행렬/벡터 조립, sparse pattern 생성
+├── Boundary/        # Fix, RBE2, RBE3 등 경계조건
+├── Core/            # Domain, AnalysisModel, AnalysisState, DofManager
+├── Element/         # Node, Element, MITC4 등 요소 구현
+├── IO/              # Abaqus input parser, HDF5 results writer
+├── Load/            # NodalLoad, PressureLoad, BodyForce 등 하중
+├── Math/            # Vector, Matrix, SparseMatrix, MKL adapter
+├── Material/        # LinearElastic 등 재료 모델
+├── Property/        # ShellProperty, 1D/2D/3D property
+├── Results/         # Step, Frame, FieldOutput, HistoryOutput
+└── Util/            # 공통 유틸리티, 로깅, 검증 보조 함수
+```
+
+## 핵심 클래스 구조
+```
+Domain
+├── Node
+├── Element
+├── Material
+├── Property
+├── NodeSet
+├── ElementSet
+├── BoundaryCondition
+├── Load
+└── StepDefinition
+
+AnalysisModel
+├── active elements
+├── active loads
+├── active boundary conditions
+├── active properties/materials
+└── equation system view
+
+AnalysisState
+├── displacement U
+├── velocity V
+├── acceleration A
+├── temperature T
+├── external force Fext
+├── internal force Fint
+├── residual R
+├── current time / increment / iteration
+└── element state / integration point state
+
+DofManager
+├── node dof definitions
+├── constrained/free dof mapping
+├── equation numbering
+├── sparse matrix pattern ownership
+└── full/reduced vector reconstruction
+
+Analysis
+├── LinearStaticAnalysis
+├── NonlinearStaticAnalysis
+├── DynamicAnalysis
+├── FrequencyAnalysis
+└── HeatTransferAnalysis
+
+Element
+├── 1DElement
+│   ├── Truss
+│   └── Beam
+├── 2DElement
+│   ├── MITC3
+│   └── MITC4
+└── 3DElement
+    ├── Hexahedral
+    ├── Tetrahedral
+    ├── Wedge
+    └── Pyramid
+
+BoundaryCondition
+├── Fix
+├── RBE2
+└── RBE3
+
+Load
+├── NodalLoad
+├── PressureLoad
+└── BodyForce
+
+Results
+├── ResultStep
+├── ResultFrame
+├── FieldOutput
+└── HistoryOutput
+
+InputParser
+ResultsWriter
+Assembler
+LinearSolver
+Vector
+Matrix
+SparseMatrix
+```
+
+## 디자인 패턴
+
+### Strategy Pattern
+해석 알고리즘과 수치 알고리즘을 교체 가능하게 구성한다.
+
+적용 대상:
+- `Analysis`: `LinearStaticAnalysis`, `NonlinearStaticAnalysis`, `DynamicAnalysis`, `HeatTransferAnalysis`
+- `LinearSolver`: `MKLPardisoSolver`, 향후 iterative solver
+- `TimeIntegrator`: `HHTIntegrator`, 향후 Newmark 등
+- `ConvergenceCriteria`: residual norm, displacement norm, energy norm
+
+### Template Method Pattern
+해석 실행의 큰 흐름은 `Analysis::run()`에서 고정하고, 세부 단계는 해석 종류별로 재정의한다.
+
+기본 흐름:
+```
+initialize
+buildAnalysisModel
+buildDofMap
+buildSparsePattern
+assemble
+applyBoundaryConditions
+solve
+updateState
+writeResults
+```
+
+비선형 정적해석은 위 흐름을 Newton-Raphson 반복 루프 안에서 사용하고, 동적해석은 time step/frame 루프 안에서 사용한다.
+
+### Factory + Registry Pattern
+Abaqus input keyword와 내부 객체 생성을 분리한다.
+
+예:
+- `*Element, type=S4` -> `MITC4ElementFactory`
+- `*Material`, `*Elastic` -> `LinearElasticMaterialFactory`
+- `*Boundary` -> `FixBoundaryFactory`
+- `*Cload` -> `NodalLoadFactory`
+- `*Nset`, `*Elset` -> set registry
+
+요소, 재료, 하중, 경계조건 타입 추가 시 parser 본체의 변경을 최소화한다.
+
+### Adapter Pattern
+MKL, TBB, HDF5 API는 solver core에 직접 노출하지 않는다.
+
+적용 대상:
+- `SparseMatrix`, `Vector`, `Matrix`
+- `LinearSolver`
+- `ParallelFor`
+- `ResultsWriter`
+
+외부 라이브러리 교체 또는 테스트 double 사용이 가능하도록 adapter 계층에서 의존성을 제한한다.
+
+### Runtime Polymorphism
+요소, 재료, 하중, 경계조건은 base interface를 통해 다룬다. Phase 1에서는 명확성과 테스트 가능성을 우선하고, 대규모 모델 성능 최적화가 필요할 경우 assembly 내부에서 타입별 batch 처리 또는 kernel 분리를 추가한다.
+
+## 상태 관리
+
+### Domain
+`Domain`은 입력 파일에서 만들어진 전체 모델 정의를 소유한다. 파싱 이후에는 가능한 한 불변으로 취급한다.
+
+포함 대상:
+- nodes, elements
+- materials, properties
+- node sets, element sets
+- loads, boundary conditions
+- analysis step definitions
+
+### AnalysisModel
+`AnalysisModel`은 현재 step에서 활성화되는 해석 객체들의 실행 view이다. `Domain`을 복사하지 않고 참조 또는 id 기반 view로 구성한다.
+
+포함 대상:
+- active elements
+- active loads
+- active boundary conditions
+- active property/material references
+- current equation system view
+
+### DofManager
+`DofManager`는 자유도와 방정식 번호를 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.
+
+책임:
+- node별 활성 자유도 정의
+- constrained/free dof mapping
+- equation numbering
+- sparse matrix pattern 생성에 필요한 connectivity 제공
+- 경계조건 적용 전후의 dof view 관리
+
+### AnalysisState
+`AnalysisState`는 해석 중 변하는 물리량과 반복 상태를 소유한다.
+
+포함 대상:
+- displacement, velocity, acceleration
+- temperature
+- external force, internal force, residual
+- current time, increment, Newton iteration
+- element state, integration point state
+
+Phase 1에서는 displacement 중심으로 최소 구현하되, 기하비선형과 thermal-stress coupling을 위해 element/internal state 확장 지점을 유지한다.
+
+### Results State
+결과는 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 구조로 관리한다.
+
+- `ResultStep`: 해석 step 단위 결과
+- `ResultFrame`: 정적해석의 load increment 또는 동적해석의 time frame
+- `FieldOutput`: node/element field 결과
+- `HistoryOutput`: 특정 node, element, set, reaction, energy 등의 이력 결과
+
+## 데이터 흐름
+```
+Abaqus input file
+-> InputParser
+-> Domain 생성
+-> StepDefinition 루프
+-> AnalysisModel 생성
+-> DofManager로 자유도/방정식 번호 생성
+-> sparse pattern 생성
+-> Analysis 실행
+-> Assembler로 전역 행렬/벡터 조립
+-> BoundaryCondition 적용
+-> LinearSolver 또는 nonlinear/time integration loop
+-> AnalysisState 갱신
+-> ResultsWriter로 step/frame/history 저장
+-> 다음 step 진행
+```
+
+## 성능 확장 방향
+- 행렬 조립은 element 단위 병렬화를 고려해 설계한다.
+- 전역 행렬은 대규모 모델을 위해 sparse matrix를 기본으로 한다.
+- MKL 기반 direct solver를 우선 지원하되, solver interface는 iterative solver를 추가할 수 있게 둔다.
+- 대규모 sparse solve를 위해 MKL `pardiso_64`를 사용할 수 있도록 64-bit sparse index 경계를 유지한다.
+- TBB 병렬화는 요소 stiffness 계산, element force 계산, assembly precompute 등 독립 작업부터 적용한다.
+- 정확도 검증이 끝나기 전에는 MITC4 element formulation을 과도하게 최적화하지 않는다.
+

docs/project-plan/SOLVER_IMPLEMENT_INITIAL_PLAN.md

@@ -0,0 +1,313 @@
+# MITC4 Linear Static Shell Solver Initial Implementation Plan
+
+## Summary
+FESA will implement an initial finite element structural solver feature named `mitc4-linear-static-shell`. The feature reads an Abaqus-style input file, builds an internal finite element model, performs linear static analysis with a MITC4 shell element, writes HDF5 results, and verifies those results against stored Abaqus reference artifacts.
+
+The implementation must follow the full solver development workflow:
+
+1. Define solver feature requirements.
+2. Research books, papers, manuals, and related solver implementations.
+3. Write the finite element formulation required for code implementation.
+4. Define solver input and output data contracts.
+5. Create TDD test models for both FESA and the reference solver.
+6. Implement code.
+7. Compare FESA results against reference solver results for nodal displacement, reaction, element internal force, and stress.
+8. Mark implementation complete only when result differences are within tolerance.
+9. Release the solver feature.
+
+## Scope
+Feature id: `mitc4-linear-static-shell`
+
+Included:
+- Linear static structural analysis.
+- MITC4 4-node shell element.
+- Six DOF per node: `U1, U2, U3, UR1, UR2, UR3`.
+- Single-layer isotropic linear elastic shell section.
+- Abaqus `.inp` subset input.
+- Intel oneAPI MKL CSR/PARDISO sparse linear solve.
+- Intel oneAPI TBB parallel element computation and result recovery.
+- HDF5 solver result output.
+- Stored Abaqus S4R primary reference comparison.
+- Stored Abaqus S4 diagnostic reference comparison.
+
+Excluded:
+- Nastran BDF input.
+- Nonlinear geometry.
+- Nonlinear material.
+- Dynamic analysis.
+- Buckling/eigenvalue analysis.
+- Composite/layered shell section.
+- Contact.
+- Agent-run Abaqus or Nastran execution.
+- Reference artifact generation by agents.
+- OpenSees API compatibility.
+
+## Architecture
+Use OpenSees as an architectural reference, not as an API clone. FESA should use modern C++17 ownership and small testable modules.
+
+Primary conceptual modules:
+- `Domain`: model container for nodes, elements, constraints, loads, materials, sections, and analysis metadata.
+- `Node`: id, coordinates, and six ordered DOFs.
+- `Element`: abstract element behavior for stiffness, internal force, result recovery, and connectivity.
+- `ShellMITC4Element`: four-node MITC4 implementation with 24 element DOFs.
+- `Material/Section`: isotropic elastic shell section with membrane, bending, shear, and stress recovery contract.
+- `Analysis`: linear static analysis driver.
+- `SystemOfEqn`: DOF numbering, constraints, CSR assembly, MKL PARDISO solve.
+- `ResultWriter`: HDF5 output.
+- `ReferenceComparator`: HDF5 reference comparison.
+
+## Step 1: Requirements Baseline
+Create `docs/requirements/mitc4-linear-static-shell.md`.
+
+The requirement document must define:
+- analysis type: linear static
+- element type: MITC4 shell
+- DOF order: `U1, U2, U3, UR1, UR2, UR3`
+- material: isotropic linear elastic
+- section: uniform shell thickness
+- input: Abaqus `.inp` subset
+- output: HDF5
+- verification quantities: nodal displacement, reaction, element internal force/resultant, stress
+- tolerance: single value `1e-5`
+- pass rule: `abs(error) <= 1e-5` or `relative(error) <= 1e-5`
+
+Acceptance criteria:
+- Every must requirement has a verification method.
+- Every numerical output requirement has component names and units policy.
+- Reference artifact needs are listed under `references/mitc4-linear-static-shell/`.
+
+## Step 2: Research Evidence
+Create `docs/research/mitc4-linear-static-shell-research.md`.
+
+Research must cover:
+- Dvorkin-Bathe continuum mechanics based four-node shell formulation.
+- MITC4 mixed interpolation of tensorial components.
+- Assumed transverse shear strain interpolation and shear locking.
+- OpenSees `ShellMITC4` class structure and resultants.
+- Abaqus S4/S4R behavior as practical reference elements.
+- Patch tests and Scordelis-Lo shell benchmark.
+
+The research document must separate verified source facts from implementation inference.
+
+## Step 3: FEM Formulation
+Create `docs/formulations/mitc4-linear-static-shell-formulation.md`.
+
+The formulation must define:
+- reference coordinates and node ordering.
+- shell midsurface interpolation.
+- director and local coordinate basis policy.
+- six-DOF nodal displacement vector.
+- membrane, bending, transverse shear strain measures.
+- MITC transverse shear tying/interpolation.
+- isotropic shell constitutive matrix.
+- element stiffness expression.
+- 2x2 Gauss integration.
+- drill stiffness policy.
+- stress and resultant recovery.
+- invalid Jacobian and degenerate element checks.
+
+Default drill stiffness policy:
+- v0 hardcodes `alpha=1`.
+- `Ktt = alpha * min_eigenvalue(D_membrane)`.
+- Input override is deferred to a later phase.
+
+## Step 4: I/O Contract
+Create `docs/io-definitions/mitc4-linear-static-shell-io.md`.
+
+Input subset:
+- `*NODE`
+- `*ELEMENT, TYPE=S4`
+- `*ELEMENT, TYPE=S4R`
+- `*MATERIAL`
+- `*ELASTIC`
+- `*SHELL SECTION`
+- `*BOUNDARY`
+- `*CLOAD`
+- `*STEP`
+
+Output format:
+- HDF5 file.
+- No CSV output is required for this feature.
+
+Required HDF5 layout:
+```text
+/metadata
+  feature_id
+  solver_version
+  model_id
+  units
+  tolerance
+  reference_solver
+
+/mesh/nodes
+/mesh/elements/mitc4/connectivity
+
+/results/step_000/frame_000/nodal/displacement
+/results/step_000/frame_000/nodal/reaction
+/results/step_000/frame_000/element/forces
+/results/step_000/frame_000/element/stress
+```
+
+Required result components:
+- displacement: `U1, U2, U3, UR1, UR2, UR3`
+- reaction: `RF1, RF2, RF3, RM1, RM2, RM3`
+- element force/resultant: `N11, N22, N12, M11, M22, M12, Q13, Q23`
+- stress: `S11, S22, S12, S13, S23`
+
+## Step 5: TDD Reference Models
+Create `docs/reference-models/mitc4-linear-static-shell-reference-models.md`.
+
+Reference policy:
+- FESA agents do not run Abaqus or Nastran.
+- Stored Abaqus S4R HDF5 artifacts are the primary pass/fail reference.
+- Stored Abaqus S4 HDF5 artifacts are diagnostic only.
+
+Initial model portfolio:
+- membrane patch
+- bending patch
+- transverse shear patch
+- twist patch
+- coarse Scordelis-Lo shell
+
+Each model bundle must include:
+```text
+references/mitc4-linear-static-shell/<model-id>/
+  model.inp
+  metadata.json
+  abaqus_s4r/results.h5
+  abaqus_s4/results.h5
+  README.md
+```
+
+`metadata.json` must record:
+- model id
+- source/provenance
+- Abaqus version
+- element type
+- units
+- output locations
+- tolerance `1e-5`
+- compared quantities
+- known limitations
+
+## Step 6: Code Implementation Plan
+Create `docs/implementation-plans/mitc4-linear-static-shell-implementation-plan.md`.
+
+Implementation must be TDD-first:
+
+1. Write failing parser tests.
+2. Implement minimum Abaqus `.inp` parser behavior.
+3. Write failing MITC4 element tests.
+4. Implement shape functions, Jacobian checks, MITC shear interpolation, stiffness, and recovery.
+5. Write failing assembly tests.
+6. Implement DOF numbering, constraint handling, and deterministic CSR assembly.
+7. Write failing MKL PARDISO solve tests.
+8. Implement solver wrapper and reaction recovery.
+9. Write failing TBB deterministic parallel tests.
+10. Implement TBB parallel element computations with deterministic merge.
+11. Write failing HDF5 schema tests.
+12. Implement HDF5 C API RAII wrapper and result writer.
+13. Write failing reference comparison tests.
+14. Implement HDF5 reference comparator.
+15. Run full validation.
+
+Required validation commands:
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -L mitc4
+```
+
+## Step 7: Reference Verification
+Create `docs/reference-verifications/mitc4-linear-static-shell-reference-verification.md`.
+
+Comparison inputs:
+- FESA `results.h5`
+- stored Abaqus S4R `results.h5`
+- diagnostic Abaqus S4 `results.h5`
+- metadata tolerance and schema version
+
+Compared quantities:
+- nodal displacement
+- nodal reaction
+- element internal force/resultant
+- stress
+
+Matching rules:
+- node id for nodal quantities
+- element id plus Gauss point id for element quantities
+- component name for scalar comparisons
+
+Pass rule:
+```text
+abs(error) <= 1e-5 OR relative(error) <= 1e-5
+```
+
+Report:
+- compared quantity
+- number of matched rows
+- missing rows
+- extra rows
+- maximum absolute error
+- maximum relative error
+- worst id
+- worst component
+- pass/fail
+
+## Step 8: Completion Decision
+Implementation is complete only when:
+- all required tests pass;
+- CMake/MSVC/x64/Debug build passes;
+- all required HDF5 result quantities compare within tolerance `1e-5`;
+- no required reference artifact is missing;
+- failures are not hidden as known limitations.
+
+If comparison fails, classify the failure as one of:
+- missing reference artifact
+- schema mismatch
+- id mismatch
+- unit or coordinate mismatch
+- formulation defect
+- implementation defect
+- tolerance failure
+- reference artifact issue
+
+Then return to the owning workflow step.
+
+## Step 9: Release
+Create `docs/releases/mitc4-linear-static-shell-release.md`.
+
+Release document must include:
+- feature id and scope
+- supported input keywords
+- supported outputs
+- dependency versions
+- test model list
+- reference comparison summary
+- tolerance policy
+- known limitations
+- validation commands and status
+
+Release is not approved by build success alone. Release requires reference comparison success and documented limitations.
+
+## Dependency Plan
+MKL:
+- Use oneAPI MKL through `MKLROOT` or known oneAPI path.
+- Use CSR matrix storage and PARDISO for the global linear system.
+
+TBB:
+- Use oneAPI TBB through `TBBROOT` or known oneAPI path.
+- Parallelize element-local stiffness and result recovery.
+- Use deterministic merge for global assembly.
+
+HDF5:
+- FESA provides an internal RAII wrapper around the HDF5 C API.
+- The HDF5 C library itself must be supplied through `HDF5_ROOT` or `HDF5_DIR`.
+- HDF5 is required for solver output and reference comparison.
+
+## Assumptions
+- Abaqus reference artifacts are generated outside the agent workflow.
+- S4R is the primary reference for pass/fail.
+- S4 is diagnostic and does not determine pass/fail.
+- The single tolerance value is `1e-5`.
+- The initial implementation prioritizes correctness and traceability over broad element coverage.

docs/project-plan/SOLVER_SKILL_DESIGN.md

@@ -0,0 +1,181 @@
+# FESA Solver Skill Rebuild Plan
+
+## 목적
+
+이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 project-local Codex skill 구성을 정의한다.
+
+Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 절차와 검증 도구 단위다. 따라서 skill은 Agent와 1:1로 대응하지 않는다. 대신 요구조건, 연구, 정식화, I/O 계약, reference model, C++ TDD 구현, reference 비교, 물리 검토, release readiness처럼 솔버 개발 과정에서 반복되는 작업 흐름을 기준으로 구성한다.
+
+## 설계 원칙
+
+- Skill은 `.codex/skills/<skill-name>/SKILL.md`에 둔다.
+- 각 skill은 필수 frontmatter `name`, `description`과 UI metadata `agents/openai.yaml`을 가진다.
+- Skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 입력, 절차, 산출물, 금지사항, 품질 gate, handoff를 정의한다.
+- Skill은 `AGENTS.md`와 `docs/AGENT_RULES.md`를 공통 상위 기준으로 읽는다.
+- Abaqus, Nastran 또는 reference solver 실행은 skill 범위에 포함하지 않는다.
+- Reference CSV 생성 또는 수정은 skill 범위에 포함하지 않는다.
+- C++ 구현 관련 skill은 C++17 이상, MSVC, CMake, CTest, TDD 원칙을 따른다.
+- 기본 workspace validation 명령은 `python scripts/validate_workspace.py`이다.
+
+## Skill 구성
+
+| Skill | 적용 개발 과정 | 주요 사용자 Agent | 대표 산출물 |
+| --- | --- | --- | --- |
+| `fesa-requirements-baseline` | 1. 솔버 기능 요구조건 정의 | Requirement Agent, Coordinator Agent | `docs/requirements/<feature-id>.md` |
+| `fesa-research-evidence` | 2. 책, 논문 등 연구자료 조사 | Research Agent, Formulation Agent | `docs/research/<feature-id>-research.md` |
+| `fesa-formulation-spec` | 3. 코드 구현을 위한 유한요소 정식화 | Formulation Agent, Implementation Planning Agent | `docs/formulations/<feature-id>-formulation.md` |
+| `fesa-numerical-review` | 3. 정식화 독립 수치 검토 | Numerical Review Agent, Coordinator Agent | `docs/numerical-reviews/<feature-id>-review.md` |
+| `fesa-io-contract` | 4. 솔버 입출력 데이터 정의 | I/O Definition Agent, Reference Verification Agent | `docs/io-definitions/<feature-id>-io.md` |
+| `fesa-reference-models` | 5. TDD/reference 테스트모델 작성 | Reference Model Agent, Implementation Planning Agent | `docs/reference-models/<feature-id>-reference-models.md` |
+| `fesa-cpp-msvc-tdd` | 6. 코드 구현 및 build/test correction | Implementation Planning Agent, Implementation Agent, Build/Test Executor Agent, Correction Agent | implementation plan/report, build/test report, correction report |
+| `fesa-reference-comparison` | 7. reference solver 결과와 구현 solver 결과 비교 | Reference Verification Agent | `docs/reference-verifications/<feature-id>-reference-verification.md` |
+| `fesa-physics-sanity` | 8. tolerance 통과 후 물리 타당성 검토 | Physics Evaluation Agent | `docs/physics-evaluations/<feature-id>-physics-evaluation.md` |
+| `fesa-release-readiness` | 9. 솔버 기능 배포 준비 | Release Agent, Coordinator Agent | `docs/releases/<feature-id>-release.md` |
+
+## 개발 과정별 사용 예
+
+예시 기능: `linear-truss-1d`
+
+1. Requirement Agent는 `fesa-requirements-baseline`을 사용해 기능 범위, 제외 범위, 입력, 출력, 검증 물리량, tolerance, `Requirement Verification Matrix`를 작성한다.
+2. Research Agent는 `fesa-research-evidence`를 사용해 truss/bar element 이론, benchmark 후보, source reliability, applicability limits를 정리한다.
+3. Formulation Agent는 `fesa-formulation-spec`을 사용해 strong form, weak form, shape functions, B matrix, element stiffness, output recovery를 정리한다.
+4. Numerical Review Agent는 `fesa-numerical-review`를 사용해 rigid body modes, patch test, stiffness symmetry, Jacobian, locking 위험을 검토하고 `pass-for-implementation-planning` 여부를 판단한다.
+5. I/O Definition Agent는 `fesa-io-contract`를 사용해 지원할 Abaqus `.inp` keyword subset과 `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` schema를 정의한다.
+6. Reference Model Agent는 `fesa-reference-models`를 사용해 `references/linear-truss-1d/<model-id>/` artifact bundle 계약과 coverage matrix를 작성한다.
+7. Implementation Planning Agent와 Implementation Agent는 `fesa-cpp-msvc-tdd`를 사용해 테스트 작성, 실패 확인, 최소 구현, CMake/CTest 등록, validation을 수행한다.
+8. Reference Verification Agent는 `fesa-reference-comparison`을 사용해 구현 solver CSV와 저장된 reference CSV를 tolerance 기준으로 비교한다.
+9. Physics Evaluation Agent는 `fesa-physics-sanity`를 사용해 global equilibrium, reaction consistency, displacement direction, symmetry, model coverage를 검토한다.
+10. Release Agent는 `fesa-release-readiness`를 사용해 gate evidence, acceptance traceability, known limitations, release notes draft를 작성한다.
+
+## Skill별 핵심 계약
+
+### `fesa-requirements-baseline`
+
+- 기능 요청을 검증 가능한 요구조건 baseline으로 만든다.
+- `shall` 문장과 `FESA-REQ-<FEATURE>-###` id를 사용한다.
+- 모든 `must` 요구조건은 verification method와 acceptance criteria를 가져야 한다.
+- FEM 정식화, C++ 구현, reference CSV 생성, release readiness 판단은 하지 않는다.
+
+### `fesa-research-evidence`
+
+- 연구 질문, source inventory, source reliability tier, benchmark 후보를 정리한다.
+- 검증된 사실과 추론을 분리한다.
+- source gap은 open issue로 남긴다.
+- FEM 정식화 확정이나 reference value 생성을 하지 않는다.
+
+### `fesa-formulation-spec`
+
+- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분해 작성한다.
+- Jacobian, derivative transform, numerical integration, output recovery, numerical risks를 명시한다.
+- C++ API, parser, file ownership은 설계하지 않는다.
+- Numerical Review Agent 검토 전 최종 승인 상태로 두지 않는다.
+
+### `fesa-numerical-review`
+
+- 정식화를 수치 알고리즘 계약으로 독립 검토한다.
+- dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다.
+- `pass-for-implementation-planning`은 구현 계획 가능 상태만 의미한다.
+- 정식화 문서를 직접 수정하지 않는다.
+
+### `fesa-io-contract`
+
+- FESA solver input이 지원할 Abaqus `.inp` subset을 정의한다.
+- model data와 history data를 구분한다.
+- 내부 semantic model 계약과 output/CSV schema를 정의한다.
+- parser 구현이나 full Abaqus compatibility claim은 하지 않는다.
+
+### `fesa-reference-models`
+
+- smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다.
+- `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다.
+- `model.inp`, `metadata.json`, `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv`를 기준 artifact로 둔다.
+- Reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts`로 둔다.
+
+### `fesa-cpp-msvc-tdd`
+
+- C++ 구현을 `RED -> GREEN -> VERIFY` 순서로 수행한다.
+- C++ production 변경에는 관련 C++ test file이 있어야 한다.
+- 기본 검증 명령:
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest -C Debug -R <feature-or-label>
+```
+
+- 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다.
+- 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다.
+
+### `fesa-reference-comparison`
+
+- `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서로 수행한다.
+- `metadata.json`, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다.
+- max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다.
+- Reference pass는 physics validation이나 release readiness를 의미하지 않는다.
+
+### `fesa-physics-sanity`
+
+- Reference comparison 통과 후 물리 타당성을 검토한다.
+- global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, model coverage를 확인한다.
+- 문서화된 물리 기대값이 없으면 pass를 선언하지 않는다.
+- `pass-for-release-agent`는 Release Agent 검토 가능 상태만 의미한다.
+
+### `fesa-release-readiness`
+
+- `GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT` 순서로 수행한다.
+- `pass-for-reference-verification`, `pass-for-physics-evaluation`, `pass-for-release-agent` evidence를 요구한다.
+- Known Limitations와 Release Notes Draft를 작성한다.
+- 사용자 명시 요청 없이 publish, deploy, package, tag, commit, external release를 수행하지 않는다.
+
+## Agent와 Skill 관계
+
+| Agent | 주로 사용하는 Skill |
+| --- | --- |
+| Coordinator Agent | `fesa-requirements-baseline`, `fesa-reference-models`, `fesa-release-readiness` |
+| Requirement Agent | `fesa-requirements-baseline` |
+| Research Agent | `fesa-research-evidence` |
+| Formulation Agent | `fesa-formulation-spec` |
+| Numerical Review Agent | `fesa-numerical-review` |
+| I/O Definition Agent | `fesa-io-contract` |
+| Reference Model Agent | `fesa-reference-models` |
+| Implementation Planning Agent | `fesa-formulation-spec`, `fesa-reference-models`, `fesa-cpp-msvc-tdd` |
+| Implementation Agent | `fesa-cpp-msvc-tdd` |
+| Build/Test Executor Agent | `fesa-cpp-msvc-tdd` |
+| Correction Agent | `fesa-cpp-msvc-tdd` |
+| Reference Verification Agent | `fesa-reference-comparison`, `fesa-io-contract` |
+| Physics Evaluation Agent | `fesa-physics-sanity` |
+| Release Agent | `fesa-release-readiness` |
+
+## 검증 기준
+
+Skill 구성 검증은 `scripts/test_fesa_solver_skills.py`가 담당한다.
+
+검증 항목:
+
+- 10개 solver skill의 `SKILL.md` 존재 여부
+- YAML frontmatter의 `name`, `description`
+- 공통 섹션: `Inputs`, `Workflow`, `Output Contract`, `Boundaries`, `Quality Gate`, `Handoff`
+- `AGENTS.md`와 `docs/AGENT_RULES.md` 참조
+- skill-specific 핵심 문구와 산출물 경로
+- `agents/openai.yaml` UI metadata
+- 이 문서가 아니라 실제 skill 파일이 기준이 되도록 `docs/project-plan/SOLVER_SKILL_DESIGN.md`에 대한 skill 본문 참조 금지
+
+검증 명령:
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+Skill 구조 검증:
+
+```powershell
+python C:\Users\user\.codex\skills\.system\skill-creator\scripts\quick_validate.py .codex\skills\<skill-name>
+```
+
+## v1 범위
+
+- v1은 `SKILL.md`와 `agents/openai.yaml`만 포함한다.
+- 별도 `scripts/`, `references/`, `assets/`는 만들지 않는다.
+- 반복 사용 중 절차가 안정화되면 deterministic comparison script, reference artifact template, report template 같은 resource를 별도 후속 작업으로 분리한다.
+- 이 문서는 skill 구성을 설명하는 계획 문서이며, 실제 실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`이다.