add docu

2026-06-10 17:08:54 +09:00
parent 0912ee6f3b
commit c4f8f95d4b
1 changed files with 339 additions and 0 deletions
@@ -0,0 +1,339 @@
+# FESA 초기 문서 완성 계획 노트
+
+## 메타데이터
+- 작성일: 2026-06-10
+- 목적: `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`를 유한요소법 기반 구조해석 솔버 개발 프로젝트 문서로 완성하기 위한 조사 내용과 실행 계획 정리
+- 사용한 로컬 스킬: `.codex/skills/fem-theory-query`
+- 사용하지 않은 스킬: `.codex/skills/harness-workflow`
+- 현재 전제: C++17 이상, MSVC, CMake, CTest, Intel oneAPI MKL, Intel oneAPI TBB, Abaqus `.inp` 입력, HDF5 결과 저장
+
+## 성공 기준
+- `AGENTS.md`는 이 프로젝트에서 Codex agent가 따라야 할 솔버 개발 원칙, 금지사항, 검증 경로, agent/skill 사용 규칙을 명확히 정의한다.
+- `docs/PRD.md`는 FESA 구조해석 솔버의 제품 목표, v0/v1 범위, 기능 요구조건, 비기능 요구조건, 검증 gate를 정의한다.
+- `docs/ARCHITECTURE.md`는 C++ 솔버 코드 구조, 모듈 경계, 데이터 흐름, 외부 라이브러리 경계, 테스트 구조를 구현 계획에 쓸 수 있을 정도로 정의한다.
+- 세 문서는 기존 Harness 규칙을 없애지 않고, 솔버 개발 워크플로우의 운영 기반으로 흡수한다.
+- 문서 완성 후 기본 검증 경로는 계속 `python scripts/validate_workspace.py`이다.
+
+## 현재 저장소 기준선
+- 현재 `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`는 주로 C++/MSVC Harness scaffold를 설명한다.
+- `docs/SOLVER_AGENT_DESIGN.md`와 `docs/SOLVER_SKILL_DESIGN.md`는 이미 FESA 솔버 개발 workflow를 요구조건, 연구, 정식화, I/O, reference model, 구현, reference 비교, 물리 검토, release로 분해해 둔 좋은 기준 문서다.
+- `.codex/agents`에는 `requirement-agent`, `research-agent`, `formulation-agent`, `io-definition-agent`, `reference-model-agent`, `implementation-agent`, `reference-verification-agent`, `physics-evaluation-agent`, `release-agent` 등 workflow별 agent가 이미 존재한다.
+- `.codex/skills`에는 `fesa-requirements-baseline`, `fesa-research-evidence`, `fesa-formulation-spec`, `fesa-io-contract`, `fesa-reference-models`, `fesa-cpp-msvc-tdd`, `fesa-reference-comparison`, `fesa-physics-sanity`, `fesa-release-readiness`가 이미 존재한다.
+
+결론: 세 문서는 "Harness 프로젝트" 문서가 아니라 "FESA 구조해석 솔버 프로젝트" 문서로 승격해야 한다. 다만 Harness 검증, TDD guard, phase 실행기는 솔버 개발을 통제하는 운영 인프라로 남긴다.
+
+## 로컬 FEM 위키 조사 요약
+`fem-theory-query` 스킬 지침에 따라 `D:\Obsidian\MultiPhysicsVault`의 FEM 위키를 우선 확인했다.
+
+참고한 주요 위키 페이지:
+- `[[Finite Element Method]]`: FEM은 연속체를 요소로 이산화하고, nodal DOF 기반 보간, 요소 방정식, 전역 조립, 경계조건 적용, 선형/비선형 대수계 풀이로 이어진다.
+- `[[Finite Element Program Implementation]]`: 구현은 입력 파싱, element-local 계산, global DOF mapping, sparse assembly, equation solve, stress/result recovery, output/reporting으로 나뉜다.
+- `[[Abaqus Input File Syntax]]`: Abaqus 입력은 keyword/data/comment line 기반이며 model data와 history data를 분리한다.
+- `[[Abaqus Output Database and Results Files]]`: Abaqus 결과는 field output, history output, diagnostics, restart/status/message 성격의 데이터를 구분한다.
+- `[[Static Equilibrium Equation Solvers]]`: 선형 정적 해석은 sparse 직접/반복 솔버, 제약조건 처리, 반력 복구, matrix property 확인이 핵심이다.
+- `[[Finite Element Modeling and Convergence Checks]]`: 결과 신뢰성은 코드 실행 성공이 아니라 mesh, element choice, boundary/load consistency, convergence, equilibrium, stress interpretation 검토에 달려 있다.
+
+위키 기반 핵심 판단:
+- FESA 문서의 중심 개념은 "요소 정식화"만이 아니라 "입력 모델 계약 -> 내부 semantic model -> equation system -> result contract -> reference validation"이어야 한다.
+- Abaqus `.inp` 호환은 full compatibility가 아니라 기능별 supported keyword subset으로 제한해 문서화해야 한다.
+- 결과 HDF5는 단순 파일 포맷 선택이 아니라 step/frame, field/history, coordinate system, units, output location, schema version을 담는 결과 계약이어야 한다.
+- 기능 완료 판정은 CTest 통과와 별개로 reference comparison, physics sanity, release readiness gate를 모두 통과해야 한다.
+
+## 웹 조사 요약
+확인일은 2026-06-10이다. 공식 문서와 공개 프로젝트 문서 위주로 확인했다.
+
+### FEM 코드 구조와 설계 패턴
+- OOFEM은 object-oriented finite element framework를 지향하며, 공개 저장소 구조에서 `src/core`, `src/sm` 구조해석 모듈, `src/dss` 직접 sparse solver, `tests`와 `benchmarks`를 분리한다. 이는 FESA도 `core`, `structural mechanics`, `solver backend`, `tests/references`를 분리해야 한다는 근거가 된다.
+  - 출처: [OOFEM DOAJ article](https://doaj.org/article/f41d83fc936b48ae8e98de41392a9051), [OOFEM GitHub README](https://github.com/oofem/oofem)
+- MFEM은 mesh, finite element space, linear/bilinear/nonlinear form, coefficient, boundary condition 같은 개념을 명확히 분리한다. FESA는 이를 그대로 라이브러리화하기보다, structural solver에 맞춰 `Mesh`, `DofSpace`, `ElementRoutine`, `MaterialModel`, `Assembler`, `AnalysisProcedure` 경계를 갖는 편이 적절하다.
+  - 출처: [MFEM FEM documentation](https://mfem.org/fem/), [MFEM GitHub README](https://github.com/mfem/mfem)
+- MOOSE의 Kernel 시스템은 weak form 항을 residual/Jacobian contributor로 분리하고 quadrature point 단위에서 평가한다. FESA의 비선형 확장을 고려하면 element/material routine은 residual, tangent, state update를 같은 계약 안에서 제공해야 한다.
+  - 출처: [MOOSE Kernels System](https://mooseframework.inl.gov/releases/moose/2022-06-13/syntax/Kernels/), [MOOSE NonlinearSystem](https://mooseframework.inl.gov/source/systems/NonlinearSystem.html)
+
+### Abaqus 입력과 reference 검증
+- Abaqus `.inp`는 keyword line, data line, comment line으로 구성되며 keyword/parameter는 대소문자를 구분하지 않는다. FESA parser는 이 일반 규칙과 기능별 keyword subset을 분리해서 설계해야 한다.
+  - 출처: [Abaqus Input Syntax Rules](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm)
+- Abaqus model은 model data와 history data로 나뉘며, `*STEP` 이후의 history data가 analysis procedure, load, boundary condition, output request를 정의한다. FESA 내부 모델도 이 구분을 유지해야 parser와 analysis procedure가 섞이지 않는다.
+  - 출처: [Abaqus Model Definition](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEMODRefMap/simamod-c-model.htm)
+- Abaqus Verification Guide와 Benchmarks Guide는 작은 검증 문제, 외부 benchmark, NAFEMS 계열 benchmark로 정확도와 수렴성을 확인하는 방식을 제시한다. FESA reference model portfolio도 smoke, analytical, patch, benchmark, regression 모델을 구분해야 한다.
+  - 출처: [Abaqus Verification Guide](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEVERRefMap/simaver-c-ov.htm), [Abaqus Benchmarks Guide](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEBMKRefMap/simabmk-c-ov.htm)
+
+### 결과 저장과 HDF5
+- Abaqus ODB는 field output, history output, diagnostic information을 구분한다. FESA의 HDF5 결과 schema도 같은 성격 구분을 가져야 후처리와 reference 비교가 안정적이다.
+  - 출처: [Abaqus Requesting Output to the Output Database](https://docs.software.vt.edu/abaqusv2024/English/SIMACAEOUTRefMap/simaout-c-dboutput-requestingoutput-odb.htm)
+- HDF5 C++ API는 file, group, dataset, attribute, datatype, dataspace 개념을 제공하며 RAII, exception 기반 오류 처리, type-safe interface를 지원한다. FESA 결과 writer는 HDF5 C++ API 또는 얇은 RAII wrapper를 통해 schema version, units, coordinate system, step/frame metadata를 attribute/dataset으로 기록해야 한다.
+  - 출처: [HDF5 C++ API Introduction](https://support.hdfgroup.org/documentation/hdf5/latest/h5_cpp_intro.html)
+
+### MKL/TBB 사용 방향
+- Intel oneMKL은 sparse solver, Sparse BLAS, PARDISO를 제공한다. PARDISO는 CSR 계열 sparse storage를 쓰므로 FESA 전역 행렬 표현은 CSR/COO-to-CSR 조립 경로를 기준으로 설계해야 한다.
+  - 출처: [oneMKL PARDISO reference](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-fortran/2024-1/onemkl-pardiso-parallel-direct-sparse-solver-iface.html)
+- Intel oneMKL은 CMake config file을 제공하며 `MKLConfig.cmake`를 `find_package()` 경로로 사용할 수 있다. FESA CMake는 oneMKL 발견 실패를 명확한 configure error 또는 optional feature error로 처리해야 한다.
+  - 출처: [Intel oneMKL CMake config](https://www.intel.com/content/www/us/en/docs/onemkl/developer-guide-linux/2026-0/using-the-cmake-config-file.html)
+- oneTBB `parallel_for`는 iteration space를 chunk로 나누어 병렬 실행한다. FESA에서 1차 병렬화 후보는 element-level local matrix/residual 계산이다.
+  - 출처: [oneTBB parallel_for](https://uxlfoundation.github.io/oneTBB/main/tbb_userguide/parallel_for_os.html)
+- oneMKL의 일부 함수 영역은 oneTBB로 thread된다. 특히 PARDISO는 reordering/factorization 단계에서 oneTBB thread를 사용하지만 solve 단계는 sequential로 호출된다고 문서화되어 있다. FESA는 element loop 병렬화와 MKL 내부 병렬화가 서로 oversubscription을 만들지 않도록 thread policy를 문서화해야 한다.
+  - 출처: [oneMKL functions threaded with oneTBB](https://www.intel.com/content/www/us/en/docs/onemkl/developer-guide-linux/2026-0/functions-thread-with-intel-thread-build-blocks.html)
+
+## FESA 권장 코드 구조
+문서 계획 단계의 후보 구조이며, 실제 구현 전 `ARCHITECTURE.md`에서 확정한다.
+
+```text
+src/
+  fesa/
+    core/                 # ids, status, diagnostics, units, small value types
+    io/
+      abaqus/             # .inp lexer/parser, keyword subset, include policy
+      hdf5/               # HDF5 result writer/reader, schema versioning
+    model/                # semantic model: nodes, elements, sets, materials, sections, steps
+    fem/                  # DOF space, equation numbering, quadrature, shape functions
+    elements/             # truss/bar, beam, plane, solid, shell element routines
+    materials/            # elastic/plastic material contracts and state variables
+    assembly/             # local-to-global mapping, sparse pattern, COO/CSR assembly
+    constraints/          # essential BC, MPC, penalty or elimination policies
+    solvers/
+      linear/             # MKL PARDISO backend, iterative backend boundary
+      nonlinear/          # Newton control, residual/tangent norms, increments
+    analysis/             # static, modal, dynamic, nonlinear procedure drivers
+    results/              # recovery, field/history output, diagnostics
+    validation/           # comparison metrics and tolerance helpers
+tests/
+  unit/
+  integration/
+  reference/
+references/
+  <feature-id>/
+    <model-id>/
+      model.inp
+      metadata.json
+      expected.h5 or reference CSV views
+```
+
+### 모듈 경계 원칙
+- `io/abaqus`는 syntax와 semantic mapping만 담당하고 해석 알고리즘을 알지 않는다.
+- `model`은 Abaqus keyword 문자열이 아니라 solver semantic model을 가진다.
+- `fem`은 DOF, interpolation, quadrature, local/global mapping을 제공하되 특정 analysis procedure에 종속되지 않는다.
+- `elements`와 `materials`는 local residual/tangent/stress recovery 계약을 제공한다.
+- `assembly`는 sparse pattern 생성과 local contribution 조립을 담당한다.
+- `solvers`는 MKL/TBB 세부 구현을 감추는 backend boundary를 가진다.
+- `analysis`는 step/history data를 받아 procedure를 실행하고, solver backend와 result writer를 조율한다.
+- `results`는 HDF5 schema를 통해 nodal, element, integration-point, diagnostic output을 분리한다.
+
+## 권장 설계 패턴
+- Strategy: linear solver backend, nonlinear convergence policy, constraint handling, time integration, output backend를 교체 가능한 전략으로 둔다.
+- Factory/Registry: Abaqus keyword, element type, material type을 내부 semantic object로 생성한다. 초기에는 compile-time/static registry로 충분하며 동적 plugin은 문서 범위에서 제외한다.
+- Template Method: element routine은 `gather state -> evaluate quadrature -> accumulate local matrix/vector -> recover output` 순서를 공유하되 요소별 shape function과 constitutive contract를 분리한다.
+- Adapter: MKL PARDISO, oneTBB, HDF5, Abaqus syntax를 내부 core API에서 직접 노출하지 않는다.
+- RAII: MKL handle, HDF5 file/dataset, temporary solver workspace는 수명과 오류 처리를 wrapper에 묶는다.
+- Data-oriented core: global vectors, sparse matrix arrays, DOF maps, element connectivity는 cache locality와 deterministic assembly를 우선한다.
+- Deterministic assembly: TBB element loop는 thread-local contribution buffer 또는 two-pass sparse assembly를 사용해 reference comparison의 재현성을 해치지 않도록 한다.
+- Explicit diagnostics: parser warning, unsupported keyword, singular matrix, rigid body mode, convergence failure, HDF5 schema mismatch를 구조화된 diagnostic으로 남긴다.
+
+## 세 문서별 완성 계획
+
+### 1. `AGENTS.md`
+목표: Codex agent의 행동 규칙을 FESA 솔버 개발에 맞게 재정의한다.
+
+포함할 내용:
+- 프로젝트 정체성: FESA는 C++17/MSVC 기반 FEM 구조해석 솔버이며 Harness는 개발 통제 인프라다.
+- 절대 규칙:
+  - 기본 검증은 `python scripts/validate_workspace.py`.
+  - C++ production 변경은 관련 C++ test 선행.
+  - Abaqus reference artifact 생성/복원은 명시 승인된 phase에서만 수행.
+  - `harness-workflow` 사용은 사용자가 허용할 때까지 금지.
+  - full Abaqus compatibility를 주장하지 않고 기능별 keyword subset만 지원.
+- 개발 workflow:
+  1. 요구조건 분석
+  2. 연구자료 조사
+  3. 유한요소 정식화
+  4. I/O 계약 정의
+  5. TDD 및 reference model 준비
+  6. C++ 구현
+  7. reference 비교
+  8. physics sanity
+  9. release readiness
+- agent/skill map: 기존 `.codex/agents`와 `.codex/skills/fesa-*`를 workflow 단계에 연결.
+- 문서 산출물 위치: `docs/requirements`, `docs/research`, `docs/formulations`, `docs/io-definitions`, `docs/reference-models`, `docs/reference-verifications`, `docs/physics-evaluations`, `docs/releases`.
+- dependency policy: oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고, 실패 시 원인을 분류한다.
+
+검증:
+- `python -m unittest discover -s scripts -p "test_*.py"`
+- `python scripts/validate_workspace.py`
+
+### 2. `docs/PRD.md`
+목표: FESA solver product requirements를 정의한다.
+
+권장 섹션:
+- Product Vision: Abaqus `.inp` subset을 입력으로 받아 구조해석 결과를 HDF5로 저장하고, reference 결과와 비교 가능한 C++ solver.
+- Users:
+  - solver developer
+  - verification reviewer
+  - analyst preparing Abaqus-compatible input subsets
+  - Codex agent workflow operator
+- V0 Scope:
+  - 선형 정적 해석 골격
+  - 최소 Abaqus keyword subset: `*HEADING`, `*NODE`, `*ELEMENT`, `*NSET`, `*ELSET`, `*MATERIAL`, `*ELASTIC`, section keyword, `*BOUNDARY`, `*CLOAD`, `*STEP`, `*STATIC`, output request subset
+  - 1D truss/bar를 첫 번째 end-to-end feature 후보로 둔다.
+  - HDF5 result schema v0와 reference comparison view를 정의한다.
+- V1 Scope:
+  - 2D plane stress/strain
+  - 3D solid
+  - sparse assembly/MKL PARDISO
+  - TBB element loop 병렬화
+  - reference model portfolio 확장
+- Out of Scope:
+  - Abaqus full parser 호환
+  - Abaqus 직접 실행 자동화
+  - GUI/postprocessor
+  - Explicit dynamics, contact, plasticity, shell은 초기 범위 제외 또는 후속 feature
+- Functional Requirements:
+  - parser, semantic model, equation assembly, solver, result recovery, HDF5 output, diagnostics, reference comparison.
+- Nonfunctional Requirements:
+  - MSVC x64 Debug 검증
+  - deterministic results for reference tests
+  - schema versioning
+  - reproducible tolerance policy
+  - clear unsupported keyword diagnostics
+- Acceptance Gates:
+  - requirements approved
+  - research evidence complete
+  - formulation reviewed
+  - I/O contract approved
+  - tests fail before implementation
+  - CMake/CTest pass
+  - reference comparison pass
+  - physics sanity pass
+  - release readiness pass
+
+검증:
+- PRD의 모든 `must` 요구조건은 acceptance criteria와 verification method를 가져야 한다.
+- PRD의 범위는 `SOLVER_AGENT_DESIGN.md`, `SOLVER_SKILL_DESIGN.md`, 각 `docs/*/README.md`와 충돌하지 않아야 한다.
+
+### 3. `docs/ARCHITECTURE.md`
+목표: 구현자가 바로 TDD 계획으로 넘길 수 있는 code architecture를 정의한다.
+
+권장 섹션:
+- Architectural Goals:
+  - FEM formulation traceability
+  - explicit I/O contracts
+  - sparse linear algebra backend isolation
+  - deterministic verification
+  - incremental feature addition
+- Layered Architecture:
+  - CLI/application layer
+  - Abaqus input adapter
+  - semantic model
+  - FEM kernel
+  - assembly and constraints
+  - solver backend
+  - analysis procedure
+  - result output/HDF5
+  - validation/test harness
+- Data Flow:
+  ```text
+  Abaqus .inp
+  -> lexer/parser
+  -> keyword AST or records
+  -> semantic model
+  -> DOF numbering
+  -> element/material local evaluation
+  -> sparse assembly
+  -> constraints
+  -> MKL solver
+  -> recovery
+  -> HDF5 result
+  -> reference comparison/physics sanity
+  ```
+- Dependency Rules:
+  - `core`는 외부 라이브러리에 의존하지 않는다.
+  - `io/hdf5`만 HDF5에 직접 의존한다.
+  - `solvers/linear/mkl`만 oneMKL에 직접 의존한다.
+  - `parallel` 또는 `assembly` 일부만 oneTBB에 직접 의존한다.
+  - test helper는 production parser/solver 내부 상태를 우회하지 않는다.
+- Sparse Matrix Policy:
+  - assembly는 처음에는 COO triplet 수집 후 CSR finalize를 기준으로 한다.
+  - MKL PARDISO backend는 CSR input contract를 문서화한다.
+  - matrix symmetry, definiteness, singularity diagnostic을 결과에 남긴다.
+- Parallel Policy:
+  - element-local computation 병렬화를 첫 번째 TBB 적용 지점으로 둔다.
+  - 전역 sparse write는 thread-local buffer 또는 deterministic reduction으로 제한한다.
+  - MKL thread count와 TBB task arena 정책을 명시한다.
+- HDF5 Schema:
+  ```text
+  /metadata
+  /model/nodes
+  /model/elements
+  /steps/<step-name>/frames/<frame-id>/nodal/displacement
+  /steps/<step-name>/frames/<frame-id>/nodal/reaction
+  /steps/<step-name>/frames/<frame-id>/element/stress
+  /steps/<step-name>/frames/<frame-id>/element/strain
+  /diagnostics
+  ```
+- Test Architecture:
+  - unit: parser, DOF map, shape functions, material law, sparse assembly, HDF5 schema
+  - integration: small `.inp` to HDF5 end-to-end
+  - reference: Abaqus artifact comparison
+  - physics: equilibrium, sign, symmetry, rigid body mode, stress sanity
+
+검증:
+- architecture의 각 모듈은 최소 하나의 test category와 연결되어야 한다.
+- 외부 dependency는 adapter boundary 없이 core module에 직접 들어오면 안 된다.
+
+## 기존 skill/agent workflow와 문서 연결
+| Solver workflow | Agent | Skill | 문서 산출물 |
+| --- | --- | --- | --- |
+| 요구조건 분석 | `requirement-agent` | `fesa-requirements-baseline` | `docs/requirements/<feature-id>.md` |
+| 연구자료 조사 | `research-agent` | `fesa-research-evidence`, `fem-theory-query` | `docs/research/<feature-id>-research.md` |
+| 유한요소 정식화 | `formulation-agent` | `fesa-formulation-spec` | `docs/formulations/<feature-id>-formulation.md` |
+| 수치 검토 | `numerical-review-agent` | `fesa-numerical-review` | `docs/numerical-reviews/<feature-id>-review.md` |
+| I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `docs/io-definitions/<feature-id>-io.md` |
+| reference model | `reference-model-agent` | `fesa-reference-models` | `docs/reference-models/<feature-id>-reference-models.md` |
+| 구현 계획/구현 | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd` | tests, source, implementation report |
+| build/test | `build-test-executor-agent` | `fesa-cpp-msvc-tdd` | `docs/build-test-reports/<feature-id>.md` |
+| correction | `correction-agent` | `fesa-cpp-msvc-tdd` | `docs/corrections/<feature-id>.md` |
+| reference 비교 | `reference-verification-agent` | `fesa-reference-comparison` | `docs/reference-verifications/<feature-id>-reference-verification.md` |
+| 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `docs/physics-evaluations/<feature-id>-physics-evaluation.md` |
+| 배포 준비 | `release-agent` | `fesa-release-readiness` | `docs/releases/<feature-id>-release.md` |
+
+## HDF5와 기존 CSV reference skill의 정합성 이슈
+현재 프로젝트 문서와 skill은 reference comparison artifact로 CSV를 많이 언급한다. 사용자 요구조건은 solver 결과 저장 포맷을 HDF5로 지정한다.
+
+권장 결정:
+- FESA solver의 정식 결과 파일은 HDF5로 한다.
+- reference comparison을 위해 HDF5 dataset에서 deterministic CSV view를 추출하거나, comparison tool이 HDF5와 reference CSV를 직접 비교하도록 한다.
+- `docs/PRD.md`와 `docs/ARCHITECTURE.md`에는 "HDF5 authoritative output, CSV comparison view optional"을 명시한다.
+- 기존 `fesa-reference-comparison` skill은 즉시 바꾸기보다, 문서에서 HDF5 support extension을 후속 작업으로 기록한다.
+
+## 주요 리스크와 열린 질문
+- 첫 end-to-end feature를 1D truss/bar로 확정할지, 2D plane stress까지 포함할지 결정이 필요하다. 문서 계획상 v0는 1D truss/bar가 가장 안전하다.
+- oneMKL interface는 LP64와 ILP64 중 하나를 선택해야 한다. 초기 MSVC/x64/Debug에서는 LP64를 기본 후보로 두고 대형 모델 전환 시 ILP64를 검토한다.
+- MKL 내부 thread와 TBB element loop가 동시에 활성화될 때 oversubscription을 피할 정책이 필요하다.
+- HDF5 C++ API를 직접 쓸지, C API 위에 프로젝트 RAII wrapper를 둘지 결정이 필요하다. 초기에는 wrapper를 두고 내부 구현은 C++ API로 시작하는 편이 문서 요구에 맞다.
+- Abaqus `.inp` include path, quoted labels, abbreviated keywords, unsupported keyword diagnostics는 parser 요구조건에서 명확히 다뤄야 한다.
+- reference artifact 생성은 agent가 직접 하지 않는다는 기존 제약을 유지해야 한다. 사람이 생성한 artifact의 provenance를 `metadata.json`에 남긴다.
+
+## 실행 순서 제안
+1. `AGENTS.md` 개정
+   - Harness 중심 문구를 FESA solver 중심으로 확장한다.
+   - 기존 검증 명령과 TDD guard는 유지한다.
+   - agent/skill workflow와 금지사항을 명시한다.
+   - 검증: Python self-test, workspace validation.
+2. `docs/PRD.md` 개정
+   - 현재 "C++/MSVC Harness" PRD를 FESA solver PRD로 대체 또는 대폭 확장한다.
+   - v0/v1 scope, functional/nonfunctional requirements, out-of-scope, acceptance gates를 작성한다.
+   - 검증: 요구조건마다 verification method와 acceptance criteria가 있는지 수동 리뷰.
+3. `docs/ARCHITECTURE.md` 개정
+   - 현재 Harness architecture를 FESA solver architecture로 확장한다.
+   - Harness architecture는 "development operations layer"로 남긴다.
+   - 모듈 구조, dependency rules, data flow, HDF5 schema, MKL/TBB policy, test architecture를 작성한다.
+   - 검증: module/test mapping과 dependency rule 수동 리뷰.
+4. 문서 정합성 점검
+   - `docs/SOLVER_AGENT_DESIGN.md`, `docs/SOLVER_SKILL_DESIGN.md`, `docs/*/README.md`와 용어/경로 충돌을 점검한다.
+   - `python -m unittest discover -s scripts -p "test_*.py"` 실행.
+   - `python scripts/validate_workspace.py` 실행.
+
+## 후속 작업 후보
+- HDF5 result schema ADR 작성.
+- Abaqus `.inp` v0 keyword subset ADR 작성.
+- MKL/TBB threading policy ADR 작성.
+- `fesa-reference-comparison` skill의 HDF5 comparison 확장 계획 작성.
+- 첫 기능 `linear-truss-1d`의 `docs/requirements/linear-truss-1d.md` 작성.