docs: simplify FESA reference validation policy

2026-08-12 03:19:20 +09:00
parent 0e785154d4
commit 5c08f1cf83
6 changed files with 178 additions and 50 deletions
@@ -17,12 +17,21 @@
 - 주요 아키텍처 결정과 그 이유 및 트레이드오프는 `docs/ADR.md`에서 확인한다.
 - AI 에이전트는 설계나 구현 결정을 내리기 전에 PRD에서 제품 범위를, ARCHITECTURE에서 소유권과 데이터 흐름을, ADR에서 이미 결정된 트레이드오프를 먼저 확인한다. 기능별 의미는 `docs/requirements/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`의 승인 문서를 source of truth로 삼는다.
 - Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다. 전체 실행 흐름은 `docs/HARNESS_WORKFLOW.md`, 설치와 설정은 `docs/HARNESS.md`를 따른다.
- 문서와 구현은 full Abaqus compatibility를 주장하지 않는다. 기능별로 승인된 Abaqus keyword subset만 지원한다.
+- FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라
  Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을
  주장하거나 목표로 삼지 않는다. 수치 결과의 exact equality는 허용되지만 내부 동작
  동등성의 evidence가 아니다.
 - 기능별로 승인된 Abaqus keyword subset만 입력 형식으로 지원한다. Abaqus 결과는 승인된
  비교량의 외부 수치 reference일 뿐 FESA 내부 알고리즘 계약이 아니다.
 - 공식 solver output은 HDF5 `results.h5`이다.
 - reference 결과는 FESA와 같은 Abaqus `.inp` 모델을 Abaqus로 해석해 생성한 CSV 파일이다.
- reference artifact의 정확한 경로와 파일명은 기능별 reference model contract를 따른다. 신규 모델은 `reference/<model-id>/<model-id>_*.csv` canonical 이름을 사용한다.
+- reference case는 기능 문서가 지정한 기존 `.inp`와 실제 비교에 필요한 Abaqus CSV 경로를
- `metadata.json`은 선택 reference artifact다. 파일이 없어도 bundle을 불완전하다고 판정하지 않으며, 필수 provenance, units, coordinate system, step/frame, schema, tolerance 정보는 승인된 기능별 reference model contract에 기록한다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약과 일치하는지 확인한다.
+  그대로 사용한다. canonical 이름, legacy-alias 승인, bundle `README.md`, `metadata.json`,
- 승인된 B33 baseline은 예외적으로 `reference/cantilever beam/`의 기존 space-containing 파일명을 read-only legacy alias로 사용한다.
+  Abaqus version/provenance 또는 중복 unit/coordinate/step-frame/schema 기록은 readiness
  조건이 아니다.
 - 비교기는 필요한 source row identity와 component를 결정적으로 대응시키고 누락, 추가,
  중복, nonfinite 값을 tolerance 전에 거부한다. Reference artifact는 rename, rewrite 또는
  보정하지 않는다.
 - CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다.
 ## FESA 개발의 핵심 원칙
@@ -40,7 +49,7 @@
 - CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
 - CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
 - CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다.
+- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
 - CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다.
 - CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다.
 - Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
@@ -79,6 +88,22 @@
 - B33 reference row는 component별 Abaqus scale로 `absolute_floor + 1e-6 * reference_scale`을 적용한다. Reference 값을 zero-clamp하거나 누락 row를 무시하지 않는다.
 - `reference/cantilever beam/` artifact는 rename, rewrite 또는 보정하지 않는다.
 ## 승인된 MITC4 정책
 - Abaqus source `S4`와 `S4R`은 같은 FESA MITC4 정식화로 매핑하며 source type은 추적
  정보로만 보존한다. Abaqus의 S4/S4R 알고리즘을 재현하지 않는다.
 - Reference case는 `reference/shell/`의 S4 input/displacement CSV와
  `reference/shellR/`의 S4R input/displacement CSV를 현재 이름 그대로 사용한다.
 - Global `U1/U2/U3`만 blocking reference quantity다. 각 case/component에 B33과 같은
  `1e-9 + 1e-6 * reference_scale`을 적용한다. `UR1/UR2/UR3`은 같은 기준을 초과하면
  warning만 남긴다.
 - MITC4 drilling calibration, coefficient sweep, energy-ratio threshold와 별도 geometry/director
  calibration(`NR-O01`~`NR-O04`)은 구현 범위가 아니다. 6-DOF 선형계에는 물리 회전
  stiffness block의 양의 최소 대각항에 `1e-3`을 곱한 고정 numerical drilling
  stabilization만 사용하며 drilling 방향 nodal moment는 지원하지 않는다.
 - Drilling stabilization은 physical generalized strain/resultant/stress에 포함하지 않으며
  별도 drilling stiffness/ratio/energy HDF5 output을 요구하지 않는다.
 ## 기능을 추가할 때의 판단 기준
 - 새 element는 요구조건과 formulation을 승인한 뒤 semantic mapping, property/material 연결, DOF/scatter, local kernel, deterministic assembly, recovery, HDF5 row identity, reference/physics evidence를 함께 설계한다.
@@ -123,6 +148,11 @@ AI 에이전트는 유한요소 구조해석 지식이 필요할 때 FEM wiki를
 | 물리 검토 | `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` |
 Implementation Planning Agent는 구현 계획 요청에서 `.agents/skills/harness`를 반드시
 사용한다. 먼저 여러 자기완결적 Step의 초안을 제시하고 사용자 승인을 받은 뒤에만
 `phases/index.json`, `phases/<task-name>/index.json`, `phases/<task-name>/stepN.md`를
 생성한다. Harness 실행은 별도 사용자 요청이 있을 때만 수행한다.
 ## 최소 검증 진입점
 세부 target graph, dependency normalization과 Windows runtime staging은 `docs/ARCHITECTURE.md`와 실제 CMake 파일을 따른다. `.harness/config.json`이 존재하면 그 설정을 우선한다.
@@ -42,6 +42,8 @@ solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할
 **트레이드오프**: 초기 class 수가 늘어난다. V0에서는 interface를 얇게 유지하고 실제 선형 정적 frame에 필요한 state만 구현한다.
 ### ADR-005: 공식 결과 파일은 HDF5로 하고 reference 결과는 Abaqus CSV로 둔다
 **상태**: HDF5 authoritative output 결정은 유지하며 reference bundle governance 부분은 ADR-019로 대체됨.
 **결정**: FESA solver의 authoritative result output은 `results.h5` HDF5이다. Abaqus reference results는 기능별 reference model contract가 지정한 `reference/<model-id>/` 아래 CSV 파일로 저장하며, verification은 FESA HDF5 rows와 Abaqus reference CSV rows를 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 비교한다. 신규 reference는 canonical 파일명을 사용하고, 승인된 기존 bundle의 legacy alias는 해당 기능 계약에 정확한 경로를 기록한 경우에만 허용한다.
 **이유**: 구조해석 결과는 step/frame, field/history, node/element/integration point location, units, coordinate system, schema version을 함께 가져야 한다. HDF5는 이 계층 구조와 metadata를 안정적으로 표현한다.
@@ -77,6 +79,8 @@ solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할
 **트레이드오프**: 초기 병렬화 범위가 제한된다. MKL 내부 thread와 TBB task arena의 oversubscription 정책을 별도로 문서화해야 한다.
 ### ADR-010: Abaqus reference artifact는 사람이 생성하거나 명시 승인된 절차로만 갱신한다
 **상태**: Artifact read-only 및 실행 제한은 유지하며 metadata/provenance/naming 계약은 ADR-019로 대체됨.
 **결정**: Agent는 Abaqus, Nastran 또는 reference solver를 직접 실행하지 않는다. reference artifact 생성, 수정, 복원은 명시 승인된 phase에서만 수행한다. 모든 bundle의 provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance와 limitations는 승인된 기능별 Reference Model Contract에 기록한다. `metadata.json`은 선택 reference artifact이며, 부재만으로 bundle을 불완전하다고 판정하지 않는다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약 및 실제 artifact와 일치하는지 확인하며, 충돌은 숨기지 않고 upstream 계약 문제로 보고한다. 승인된 `cantilever-beam-b33` legacy baseline의 space-containing filename과 `README.md` N/A 예외는 유지한다.
 **이유**: reference 결과는 solver correctness의 기준이다. 생성 절차가 불명확하면 구현 결함과 reference artifact 오류를 구분할 수 없다.
@@ -181,3 +185,29 @@ model adequacy를 검출한다. 한 계층의 성공만으로 parser exposure
 **트레이드오프**: 작은 기능도 여러 계약과 evidence를 함께 준비해야 하므로 개발 속도가
 느려진다. 대신 `*DLOAD`처럼 kernel은 있지만 입력에 노출되지 않은 기능, stress처럼
 mandatory output이지만 Abaqus reference가 N/A인 기능을 정확하게 표현할 수 있다.
 ### ADR-019: Abaqus는 입력 형식과 외부 수치 reference이며 FESA 내부 동작 계약이 아니다
 **결정**: FESA는 Abaqus와 독립적인 솔버다. 기능별 승인 `.inp` subset을 입력으로
 사용하고, 기능이 blocking으로 선언한 FESA HDF5 quantity만 기존 Abaqus CSV와 승인
 tolerance로 비교한다. Abaqus 요소 정식화, 적분, stabilization, 내부 상태와 결과 생성
 절차를 재현하거나 동등하게 구현하지 않는다. Exact numerical equality는 허용되지만
 내부 동작 동등성의 evidence가 아니다.
 Reference case readiness에는 선언된 `.inp`, 실제 비교에 필요한 CSV, deterministic
 source-ID/component matching과 tolerance만 필요하다. 기존 path와 filename을 그대로
 사용하며 canonical naming, legacy-alias 승인, bundle `README.md`, `metadata.json`, Abaqus
 version/provenance, 중복 units/coordinates/model/step/frame/material/section 정보와 CSV schema
 version은 요구하지 않는다. Reference artifact는 계속 read-only이며 누락, 추가, 중복,
 nonfinite required row는 tolerance 전에 실패한다.
 **이유**: Reference comparison의 목적은 FESA의 독립 정식화가 승인된 observable quantity를
 충분히 가깝게 계산하는지 판정하는 것이다. 수치 비교에 사용되지 않는 artifact
 거버넌스가 formulation review나 implementation planning을 차단하면 제품 검증보다 문서
 형식 준수가 우선된다. 같은 정보는 `.inp`, CSV header와 feature contract에서 직접 얻을
 수 있다.
 **트레이드오프**: Reference 생성 환경을 사후에 완전히 재구성하는 감사 기능은 줄어든다.
 대신 비교 대상과 source-row/component mapping, tolerance, artifact immutability는 유지해
 false match와 결과 보정을 방지한다. 더 강한 provenance가 필요한 기능은 해당 요구조건이
 명시적으로 추가할 수 있으나 프로젝트 기본 gate로 자동 승격하지 않는다.
@@ -3,6 +3,11 @@
 ## 목표
 FESA의 아키텍처 목표는 Abaqus `.inp` subset을 내부 semantic model로 변환하고, 유한요소 equation system을 구성해 구조해석 결과를 HDF5로 저장하며, reference comparison과 physics sanity가 가능한 C++17/MSVC 솔버 구조를 제공하는 것이다.
 FESA의 element formulation과 numerical path는 Abaqus와 독립적이다. Abaqus `.inp`는
 승인된 입력 형식이고 Abaqus CSV는 기능별 blocking quantity의 외부 수치 reference다.
 Abaqus 내부 적분, stabilization, state 또는 recovery 동작은 FESA architecture contract가
 아니다.
 핵심 품질 속성:
 - FEM formulation traceability
 - explicit I/O contracts
@@ -42,7 +47,7 @@ tests/
  integration/             # analysis orchestration and CLI contracts
  reference/               # HDF5-to-Abaqus projection and comparison
 reference/
-  <model-id>/              # approved read-only Abaqus input/CSV bundle
+  <case-dir>/              # declared read-only Abaqus input/required CSV pair
 .agents/
  skills/                 # Harness and review skills
 .codex/
@@ -302,8 +307,11 @@ Schema requirements:
 - field output과 history output을 구분한다.
 - reference comparison을 위한 row identity는 node id, element id, integration point id, step/frame id를 포함한다.
 - FESA solver는 `results.h5`를 authoritative output으로 쓴다.
- Abaqus reference results는 `reference/<model-id>/` 아래 CSV 파일이다.
+- Abaqus reference results는 기능 문서가 선언한 기존 CSV 파일이다. Directory/file
- Verification은 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 FESA HDF5 rows와 Abaqus reference CSV rows를 비교한다.
+  naming, README, metadata 또는 provenance는 architecture readiness 조건이 아니다.
 - Verification은 기능이 요구하는 source identity와 component를 결정적으로 대응시키고
  승인 tolerance를 적용한다. Missing/extra/duplicate/nonfinite required row는 숫자 비교
  전에 실패한다. 단일 step/final-frame 기능은 별도 CSV step/frame 열을 요구하지 않는다.
 - FESA HDF5에서 추출한 deterministic CSV view는 optional debugging/review artifact이며 공식 solver output 또는 reference artifact가 아니다.
 - Writer는 final과 같은 directory의 임시 HDF5에 전체 schema를 쓴 뒤 flush, checked close,
  read-only reopen/self-check를 수행한다. Existing final은 `ReplaceFileW`, 새 final은
@@ -348,7 +356,7 @@ deterministic한 순서로 출력한다.
 | 기능 유형 | 시작 전에 고정할 것 | 주요 구현 경계 | 함께 검증할 것 | 피해야 할 shortcut |
 | --- | --- | --- | --- | --- |
-| 새 element/material | DOF, interpolation, constitutive law, integration, local axes/sign, invalid geometry/property | Domain record와 mapper, element kernel, DofManager scatter/pattern, SparseAssembler, ResultRecovery | rigid modes/rank/energy, patch·analytical test, rotated coordinates, reference/physics | 기존 TYPE을 비슷한 kernel에 alias, source ID와 internal index 혼용, 검증 전 범용 hierarchy 추가 |
+| 새 element/material | DOF, interpolation, constitutive law, integration, local axes/sign, feature-approved validity boundary | Domain record와 mapper, element kernel, DofManager scatter/pattern, SparseAssembler, ResultRecovery | feature-required invariants/tests and blocking reference quantities | 서로 다른 물리를 같다고 주장, source ID와 internal index 혼용, 검증 전 범용 hierarchy 추가 |
 | 새 load/constraint | Abaqus target grammar, application order, units, follower 여부, prescribed-value 의미 | Syntax/mapper, Domain target, full-space LoadAssembler 또는 constraint partition, diagnostics | set/direct target ambiguity, multi-instance identity, nonfinite sum, `Ff-Kfc*dc`, reaction | Element load kernel 존재를 parser 지원으로 간주, penalty를 elimination에 몰래 혼합 |
 | 새 analysis procedure | governing equation, state variables, increment/time lifecycle, tangent/residual, convergence와 output frame | 별도 Analysis implementation, procedure-specific state/equation owner, solver interface extension | orchestration order, failure atomicity, restart/frame identity, numerical benchmark | V0 hook 사이에 조건문으로 반복/시간 적분 삽입, 사용하지 않는 future state 선할당 |
 | 새 numerical backend | matrix/index contract, lifecycle, reusable state, failure taxonomy, thread/runtime policy | 기존 `LinearSolver` 또는 `ParallelFor` interface의 concrete adapter, CMake normalized target | empty/dimension/extreme-scale input, repeated call, failed-output preservation, clean runtime discovery | Vendor type을 public header에 노출, silent fallback/regularization, absolute install path 고정 |
@@ -356,3 +364,16 @@ deterministic한 순서로 출력한다.
 모든 확장은 PRD의 제품 완료 정의와 요구조건→정식화→I/O→구현→reference→physics gate를
 따른다. 기존 feature contract에 없는 범위를 편의상 “Abaqus compatible”이라고 넓히지 않는다.
 ## MITC4 확장 경계
 MITC4가 구현될 때 Abaqus `S4`와 `S4R` source type은 같은 FESA formulation을 선택한다.
 Source type은 metadata/diagnostic identity로 보존하지만 FESA integration 또는 hourglass
 경로를 선택하지 않는다. 6-DOF embedding의 비물리 drilling coordinate에는 physical
 rotational stiffness block의 positive minimum diagonal에 `1e-3`을 곱한 고정 numerical
 stabilization만 둔다. Drilling calibration, artificial-energy policy와 별도 drilling result
 dataset은 이 기능 범위가 아니다.
 Reference comparison은 `reference/shell/` S4와 `reference/shellR/` S4R의 기존 input 및
 displacement CSV를 사용한다. Global `U1/U2/U3`만 blocking이고 B33과 같은 component-scale
 mixed tolerance를 적용한다. `UR1/UR2/UR3`은 같은 기준의 warning-only evidence다.
@@ -1,9 +1,15 @@
 # PRD: FESA 구조해석 솔버
 ## 목표
-FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기반 구조해석을 수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, Abaqus reference CSV rows와 비교 가능한 C++17/MSVC 솔버를 제공한다.
+FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 자체 유한요소 정식화로 구조해석을
 수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, 기능이 지정한 Abaqus
 reference CSV 수치와 비교 가능한 C++17/MSVC 솔버를 제공한다. Abaqus의 요소 알고리즘,
 적분법, stabilization 또는 내부 결과 생성 절차를 재현하는 것은 목표가 아니다.
-이 프로젝트의 성공 기준은 단순 실행 성공이 아니다. 기능은 요구조건, 정식화, I/O 계약, C++ 테스트, reference comparison, physics sanity, release readiness를 모두 통과해야 완료된다.
+이 프로젝트의 성공 기준은 단순 실행 성공이 아니다. 기능 구현은 요구조건, 정식화,
 I/O 계약, C++ build/test와 기능별 blocking reference comparison을 통과해야 완료된다.
 Physics sanity와 release readiness는 구현 완료 뒤 별도 배포 판단을 제공하며 Abaqus 내부
 동작 동등성을 요구하지 않는다.
 ## 사용자
 - Solver developer: C++17/MSVC/CMake/CTest 환경에서 요소, 재료, 해석 절차, solver backend를 구현한다.
@@ -31,7 +37,9 @@ Element/material 계층의 일반적인 runtime polymorphism, iterative solver,
 3. 해석 procedure는 active model view, DOF/equation map과 sparse system을 만들고, essential constraint elimination을 적용해 선형계를 factorize하고 substitution한다.
 4. FESA는 full displacement를 복구하고 equilibrium residual/reaction과 element 결과를 계산한다.
 5. 성공 시 output request와 무관한 mandatory 결과, metadata와 diagnostic을 versioned `results.h5`에 기록한다. 실패 시 불완전한 최종 결과 파일을 정상 결과처럼 남기지 않는다.
-6. 검증 workflow는 HDF5 row를 승인된 Abaqus reference CSV identity에 투영해 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을 검토한다.
+6. 검증 workflow는 기능이 지정한 HDF5 quantity를 기존 Abaqus CSV의 source identity와
   component에 대응시켜 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을
   검토한다. Reference bundle naming이나 provenance는 수치 비교 gate가 아니다.
 Parser keyword, element kernel, solver backend 또는 output dataset 중 하나만 추가된 상태는 end-to-end 제품 기능이 아니다. 같은 기능의 입력 의미부터 외부 결과와 검증까지 연결되어야 한다.
@@ -76,12 +84,15 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 새로운 element, load, constraint, material, analysis procedure 또는 output quantity는 다음 조건을 모두 만족할 때 FESA 제품 기능으로 취급한다.
-1. 지원 범위와 제외 범위, 실패 category, units/coordinates/identity, tolerance가 요구조건과 I/O 계약에 명시되어 있다.
+1. 지원 범위와 제외 범위, 실패 category, solver output의 units/coordinates/identity,
   blocking reference quantity와 tolerance가 요구조건과 I/O 계약에 명시되어 있다.
 2. 필요한 FEM 정식화와 recovery/sign convention이 검토되었고, 수치 위험과 검증 문제를 numerical review가 다룬다.
 3. Syntax와 semantic mapping이 내부 모델에 안정된 source identity로 연결되며 잘못된 입력을 fail-closed로 거부한다. Kernel만 제공하는 기능은 parser/CLI 지원 여부를 별도로 표시한다.
 4. DOF, sparse pattern, assembly, constraint, solver lifecycle과 mutable state ownership이 기존 아키텍처에 연결되거나 승인된 새 procedure 경계를 가진다.
 5. Mandatory HDF5 schema와 diagnostic, CLI 실패 의미가 정의되고 failure path가 기존 state 또는 최종 output을 오염시키지 않는다.
-6. Unit test가 local 수식과 validation을, integration test가 orchestration과 외부 계약을, reference comparison과 physics sanity가 수치·물리 타당성을 각각 증명한다. Reference가 N/A이면 그 이유와 대체 evidence를 명시한다.
+6. Unit test가 local 수식과 validation을, integration test가 orchestration과 외부 계약을,
   required reference comparison이 기능별 blocking quantity의 외부 수치 acceptance를
   각각 증명한다. Reference가 N/A이면 그 이유와 대체 evidence를 명시한다.
 ## 기능 요구조건
 | ID | 요구조건 | Acceptance Criteria | Verification Method |
@@ -92,10 +103,10 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 | FESA-PRD-004 | FESA는 equation numbering과 constraint/free mapping을 `DofManager`에 집중해야 한다. | Node/Element 내부에 equation id를 분산 저장하지 않는다. | code review, DofManager unit test |
 | FESA-PRD-005 | FESA는 해석 중 변하는 물리량을 `AnalysisState`에 저장해야 한다. | V0 displacement, external/internal force, residual, constrained reaction, step/frame identity와 element recovery rows가 출력에 연결되고 velocity, acceleration, temperature, iteration history는 할당하지 않는다. | state unit test, integration test |
 | FESA-PRD-006 | FESA는 solver 결과를 HDF5 authoritative output `results.h5`로 저장해야 한다. | V0 step/frame field results, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test |
-| FESA-PRD-007 | FESA는 Abaqus reference CSV rows와 비교 가능한 deterministic row mapping을 제공해야 한다. | displacement와 reaction은 node identity, B33 section resultant는 정규화된 node station identity로 비교하고 stress reference comparison은 N/A로 기록한다. | reference comparison report |
+| FESA-PRD-007 | FESA는 기능이 지정한 Abaqus reference CSV quantity와 비교 가능한 deterministic source-row/component mapping을 제공해야 한다. | Required source IDs/components는 일대일 대응되고 missing/extra/duplicate/nonfinite row는 tolerance 전에 실패한다. Canonical naming, README, metadata, provenance 또는 CSV schema version은 요구하지 않는다. | reference comparison report |
 | FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file, RED 실패와 후속 GREEN 성공 증거가 있고 Stop의 전체 MSVC build/test가 통과한다. | implementation report, Hook guardrail, CTest |
 | FESA-PRD-009 | FESA는 외부 라이브러리 API를 solver core에 직접 노출하지 않아야 한다. | MKL, TBB, HDF5 의존은 adapter module에 제한된다. | architecture review, dependency review |
-| FESA-PRD-010 | FESA 기능 완료는 reference comparison과 physics sanity 통과를 요구해야 한다. | 수치 tolerance와 물리 검토가 모두 pass이고 known limitation이 기록된다. | verification report, physics evaluation report |
+| FESA-PRD-010 | FESA 기능 구현 완료는 build/test와 기능별 blocking reference comparison 통과를 요구해야 한다. | Required CTest가 통과하고 선언된 blocking quantity가 승인 tolerance 안에 있다. Physics sanity와 release readiness는 별도 후속 gate다. | build/test report, reference verification report |
 | FESA-PRD-011 | V0는 입력 파일당 하나의 linear static step과 Abaqus B33 3D Euler beam만 해석해야 한다. | 단일 B33 model은 해석되고, B31과 두 번째 step은 구조화된 unsupported diagnostic으로 거부된다. | parser/semantic unit test, CLI integration test |
 | FESA-PRD-012 | V0는 Part/Assembly/Instance wrapper와 source identity를 보존해야 한다. | 여러 identity instance의 node/element/set label이 stable internal ID로 deterministic하게 매핑되고 transform 또는 nested assembly는 거부된다. | semantic mapping unit test |
 | FESA-PRD-013 | Output-request allowlist는 해석 의미를 변경하지 않아야 한다. | 승인 keyword와 variable data는 warning 후 no-op이고, allowlist 밖 model-affecting keyword는 오류이며 기본 결과는 output request와 무관하게 생성된다. | parser diagnostic test, HDF5 integration test |
@@ -103,7 +114,7 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 | FESA-PRD-015 | FESA는 V0 결과와 diagnostic을 안정된 외부 계약으로 출력해야 한다. | CLI가 `0=success`, `2=usage`, `3=input`, `4=model`, `5=solver`, `6=HDF5` exit code를 사용하고 diagnostic field가 계약과 일치하며 HDF5가 displacement, reaction, end force, section resultant, generalized strain/resultant, axial `S11`을 포함하고 실패 시 불완전한 최종 파일을 남기지 않는다. | CLI integration test, HDF5 schema/atomicity test |
 | FESA-PRD-016 | Dense와 sparse math storage 및 backend 경계를 분리해야 한다. | `Vector`는 contiguous, `Matrix`는 row-major contiguous storage와 MKL CBLAS를 사용하고 `SparseMatrix`는 별도 0-based CSR 타입이며 MKL 타입이 public core API에 노출되지 않는다. | math unit test, dependency review |
 | FESA-PRD-017 | B33 reference comparison은 component-scale 혼합 tolerance를 사용해야 한다. | 모든 matched row가 `abs_error <= absolute_floor + 1e-6 * reference_scale`을 만족하고 missing/extra/nonfinite row는 comparison 전에 실패한다. | reference comparison unit/integration test, verification report |
-| FESA-PRD-018 | 승인된 B33 reference artifact는 read-only baseline으로 유지해야 한다. | `reference/cantilever beam/` 파일을 rename, rewrite, 보정하지 않고 exact legacy path로 읽으며 B33 element type과 expected headers를 artifact check에서 확인한다. | artifact inventory, Git diff review |
+| FESA-PRD-018 | 승인된 B33 reference artifact는 현재 경로의 read-only baseline으로 유지해야 한다. | `reference/cantilever beam/` 파일을 rename, rewrite 또는 보정하지 않고 기능이 선언한 exact path에서 읽는다. | artifact inventory, Git diff review |
 | FESA-PRD-019 | B33 beam section과 local axis를 Abaqus 의미에 맞게 매핑해야 한다. | `n1 -> local y`, `t x n1 -> local z`, `Iy=I11`, `Iz=I22`, `I12=0`을 적용하고 nonpositive property, zero-length element, tangent-parallel guide vector를 구조화된 model diagnostic으로 거부한다. | section-mapping unit test, element geometry test |
 ## 비기능 요구조건
@@ -113,6 +124,8 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 - B33 reference tolerance는 model, step/frame, quantity, component별 Abaqus scale만 사용한다.
 - 승인된 SI B33 bundle의 absolute floor는 displacement/rotation `1e-9`, force/moment
  `1e-3`이며 relative coefficient는 `1e-6`이다.
 - MITC4 U/UR comparison은 같은 component-scale 형식을 사용한다. `U1/U2/U3`만
  blocking이고 `UR1/UR2/UR3` 초과는 warning-only다.
 - parser, solver, HDF5 writer는 실패 원인을 구조화된 diagnostic으로 보고한다.
 - oneMKL, oneTBB, HDF5는 CMake에서 명시 탐지하고 실패 원인을 분류한다.
 - 대규모 모델 성능 최적화보다 V0의 명확성, 테스트 가능성, 검증 traceability를 우선한다.
@@ -121,10 +134,12 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 1. Requirements approved: 기능 범위, 제외 범위, 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
 2. Research evidence complete: 정식화와 benchmark 근거가 신뢰도와 한계와 함께 정리되어 있다.
 3. Formulation reviewed: 약형, shape function, B matrix, constitutive contract, 수치적분, output recovery가 검토되어 있다.
-4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract, reference CSV comparison row contract가 승인되어 있다.
+4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract,
   required reference quantity의 최소 source-ID/component matching이 승인되어 있다.
 5. Tests fail before implementation: C++/integration/reference test를 제품 코드보다 먼저 작성하고 같은 Step 안에서 RED 실패와 후속 GREEN 성공을 확인한다.
 6. CMake/CTest pass: MSVC/x64/Debug 기준 configure, build, test가 통과한다.
-7. Reference comparison pass: FESA `results.h5`의 displacement, reaction, section resultant rows가 승인된 B33 CSV와 documented identity 및 component-scale 혼합 tolerance 안에 있다. Beam stress comparison은 명시적 N/A다.
+7. Reference comparison pass: 기능이 blocking으로 선언한 FESA `results.h5` quantity가
   선언된 Abaqus CSV와 source identity/component별로 대응되고 승인된 tolerance 안에 있다.
 8. Physics sanity pass: equilibrium, reaction consistency, displacement direction, symmetry, section-force consistency와 normalized residual이 검토되어 있다.
 9. Release readiness pass: acceptance traceability, known limitations, release notes draft가 준비되어 있다.
@@ -9,7 +9,11 @@
 - 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
 - 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
 - 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference/<model-id>/`에 저장된 `model.inp`와 Abaqus reference CSV files를 검증 기준으로 사용하고, 선택 `metadata.json`이 존재하면 read-only 보조 자료로 계약과 대조한다.
+- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. 기능이 선언한 기존 `.inp`와 실제
  비교에 필요한 Abaqus CSV만 read-only 검증 기준으로 사용한다. Canonical naming,
  README, metadata, version 또는 provenance는 기본 readiness 조건이 아니다.
 - FESA는 Abaqus와 독립적인 solver다. Agent는 Abaqus 내부 formulation, integration,
  stabilization 또는 recovery equivalence를 요구하거나 추론하지 않는다.
 - 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
 - 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
 - Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.
@@ -111,12 +115,13 @@
 - 단위와 좌표계 규약
 ### Reference Model Agent
-TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.
+TDD와 검증에 사용할 기존 reference case를 inventory하는 Agent이다.
 책임:
- 개발 대상 기능을 검증할 최소 모델, benchmark 모델, 회귀 모델을 설계한다.
+- 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다.
- `reference/<model-id>/`에 보관할 Abaqus input file, metadata, Abaqus reference CSV 요구사항을 정의한다.
+- 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와
- 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다.
+  tolerance를 inventory한다.
 - FESA HDF5 quantity와 source ID/component matching을 명시한다.
 - 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.
 중요 제약:
@@ -124,18 +129,17 @@ TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.
 - Abaqus 해석 결과 CSV는 사람이 생성하거나 별도 승인된 절차로 생성해 `reference/<model-id>/`에 저장한다.
 - Agent는 저장된 reference artifact만 사용해 비교한다.
-권장 reference 구조:
+최소 reference case 구조:
 ```text
 reference/
-  <model-id>/
+  <case-dir>/
-    model.inp
+    <declared-input>.inp
-    metadata.json                       # optional
+    <declared-required-quantity>.csv
    <model-id>_displacements.csv
    <model-id>_reactions.csv
    <model-id>_internalforces.csv
    <model-id>_stresses.csv
 ```
 Directory와 filename은 제공된 값을 그대로 사용한다. Reference Model Agent는 canonical
 이름, README, metadata, provenance 또는 비교하지 않는 quantity CSV를 요구하지 않는다.
 ### Implementation Planning Agent
 코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다.
@@ -150,6 +154,15 @@ reference/
 - 테스트 우선순위
 - 변경 파일 후보
 - acceptance checklist
 - 사용자 승인 전 multi-Step Harness 초안
 - 승인 후 `phases/index.json`, `phases/<task-name>/index.json`, 자기완결적 `stepN.md`
 필수 절차:
 - 구현 계획 요청에서 project-local `$harness` skill을 사용한다.
 - 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD
  RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다.
 - Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다.
 - Harness executor 실행은 별도 사용자 요청이 있을 때만 수행한다.
 ### Implementation Agent
 C++ 코드를 구현하는 Agent이다.
@@ -251,7 +264,7 @@ Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 선언된
 | 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 요구사항 |
+| 5. Reference case 준비 | Reference Model Agent, Implementation Planning Agent | 기존 input/required CSV inventory, 비교 mapping, tolerance |
 | 6. 코드 구현 | Implementation Agent | C++ 코드, 테스트 |
 | 7. 레퍼런스 결과 비교 검증 | Reference Verification Agent, Physics Evaluation Agent | 비교 리포트, 물리 검토 |
 | 8. tolerance 만족 시 완료 | Coordinator Agent | 기능 완료 승인 |
@@ -275,8 +288,7 @@ flowchart TD
  L --> I
  K -- "예" --> M["Reference Verification Agent"]
  M --> N{"tolerance 만족?"}
-  N -- "아니오" --> O["Physics Evaluation Agent"]
+  N -- "아니오" --> L
  O --> L
  N -- "예" --> P["Physics Evaluation Agent"]
  P --> Q{"물리 검토 통과?"}
  Q -- "아니오" --> L
@@ -300,8 +312,8 @@ flowchart TD
 ### Gate 3: 테스트 준비 승인
 통과 조건:
 - 구현 전 실패해야 하는 테스트가 정의되어 있다.
- `reference/<model-id>/` artifact 요구사항이 명확하다.
+- 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다.
- 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다.
+- 필요한 source ID/component matching과 tolerance가 정의되어 있다.
 ### Gate 4: 구현 검증
 통과 조건:
@@ -312,9 +324,10 @@ flowchart TD
 ### Gate 5: 레퍼런스 검증
 통과 조건:
- Abaqus reference CSV 결과와 구현 solver HDF5 결과가 tolerance 안에 있다.
+- 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가
- 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다.
+  tolerance 안에 있다.
- 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다.
+- Warning-only quantity는 결과와 경고가 리포트에 남고 pass/fail을 바꾸지 않는다.
 - Required source row/component의 누락, 추가, 중복 또는 nonfinite 값이 없다.
 ### Gate 6: 배포 승인
 통과 조건:
@@ -371,6 +384,8 @@ Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Defin
 ## 운영 메모
 - Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건은 승인된 기능별 Reference Model Contract에 기록한다. 선택 `metadata.json`이 존재하면 read-only로 참고하고 계약과의 충돌을 보고한다.
+- 사람이 제공한 Abaqus reference artifact는 현재 path/name 그대로 read-only로 사용한다.
  별도 provenance, README 또는 metadata가 없다는 이유로 gate를 차단하지 않는다.
 - reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
- 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다.
+- 기능 구현 완료 판정은 build/test와 기능별 blocking reference validation 통과를 기준으로
  한다. Physics evaluation과 release readiness는 별도 후속 배포 gate다.
@@ -42,8 +42,11 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 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, `results.h5` schema, reference CSV comparison row schema를 정의한다.
-6. Reference Model Agent는 `fesa-reference-models`를 사용해 `reference/<model-id>/` artifact bundle 계약과 coverage matrix를 작성한다.
+6. Reference Model Agent는 `fesa-reference-models`를 사용해 기존 input/required CSV
-7. Implementation Planning Agent와 Implementation Agent는 `fesa-cpp-msvc-tdd`를 사용해 테스트 작성, 실패 확인, 최소 구현, CMake/CTest 등록, validation을 수행한다.
+   reference-case inventory와 비교 mapping을 작성한다.
 7. Implementation Planning Agent는 먼저 project-local `harness`를 사용해 사용자 승인용
   multi-Step 초안을 만들고, 승인 후 phase files를 생성한다. 그 뒤 Implementation Agent와
   함께 `fesa-cpp-msvc-tdd` 계약에 따라 RED/GREEN/VERIFY를 수행한다.
 8. Reference Verification Agent는 `fesa-reference-comparison`을 사용해 구현 solver `results.h5` rows와 Abaqus reference CSV rows를 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를 작성한다.
@@ -77,6 +80,8 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 - dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다.
 - `pass-for-implementation-planning`은 구현 계획 가능 상태만 의미한다.
 - 정식화 문서를 직접 수정하지 않는다.
 - 이후 Reference Model 문서, artifact naming, README, metadata, provenance 또는 portfolio가
  없다는 이유로 formulation verdict를 실패시키지 않는다.
 ### `fesa-io-contract`
@@ -87,10 +92,11 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 ### `fesa-reference-models`
- smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다.
+- 기능이 실제로 사용하는 기존 reference case를 inventory한다.
- `reference/<model-id>/` artifact bundle 계약을 정의한다.
+- Exact input/required CSV path, case purpose, blocking/warning quantity, HDF5 projection,
- `model.inp`와 요구된 `<model-id>_displacements.csv`, `<model-id>_reactions.csv`, `<model-id>_internalforces.csv`, `<model-id>_stresses.csv`를 기준 artifact로 둔다. 필수 provenance는 Reference Model Contract에 기록하고, 선택 `metadata.json`이 존재하면 read-only로 대조한다.
+  source ID/component matching과 tolerance만 정의한다.
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts`로 둔다.
+- Required comparison file이 없을 때만 `needs-reference-artifacts`로 둔다. Canonical naming,
  README, metadata, provenance와 비교하지 않는 quantity CSV는 요구하지 않는다.
 ### `fesa-cpp-msvc-tdd`
@@ -115,10 +121,21 @@ uv run --with pytest python -m pytest -v -rs
 - 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다.
 - 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다.
 ### project-local `harness`
 - Implementation Planning Agent가 구현 요청을 여러 독립 Step으로 분해할 때 사용한다.
 - 한 Step은 하나의 layer/module만 소유하고 prerequisite file, TDD RED/GREEN/VERIFY,
  exact acceptance command와 구체적 금지사항을 포함한다.
 - 사용자에게 Step 초안을 먼저 제시한다. 승인 후에만 `phases/index.json`,
  `phases/<task-name>/index.json`, `phases/<task-name>/stepN.md`를 생성한다.
 - 계획 작성과 executor 실행을 구분하며, `scripts/execute.py`는 별도 사용자 요청 없이
  실행하지 않는다.
 ### `fesa-reference-comparison`
 - `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서로 수행한다.
- `model.inp`, `results.h5`, Abaqus reference CSV files, Reference Model Contract의 provenance, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다. 선택 `metadata.json`이 존재하면 inventory하고 계약과 대조하되, 부재만으로 비교를 중단하지 않는다.
+- 선언된 input, required Abaqus CSV, `results.h5`, source ID/component mapping과 tolerance를
  확인한다. Missing/extra/duplicate/nonfinite required row는 비교 전에 실패한다.
 - max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다.
 - Reference pass는 physics validation이나 release readiness를 의미하지 않는다.
@@ -147,7 +164,7 @@ uv run --with pytest python -m pytest -v -rs
 | 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 Planning Agent | project-local `harness`, `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` |