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
@@ -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 모델, 회귀 모델을 설계한다.
- `reference/<model-id>/`에 보관할 Abaqus input file, metadata, Abaqus reference CSV 요구사항을 정의한다.
- 레퍼런스 결과에 포함될 물리량과 tolerance를 명시한다.
+- 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다.
+- 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와
+  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>/
-    model.inp
-    metadata.json                       # optional
-    <model-id>_displacements.csv
-    <model-id>_reactions.csv
-    <model-id>_internalforces.csv
-    <model-id>_stresses.csv
+  <case-dir>/
+    <declared-input>.inp
+    <declared-required-quantity>.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"]
-  O --> L
+  N -- "아니오" --> L
  N -- "예" --> P["Physics Evaluation Agent"]
  P --> Q{"물리 검토 통과?"}
  Q -- "아니오" --> L
@@ -300,8 +312,8 @@ flowchart TD
 ### Gate 3: 테스트 준비 승인
 통과 조건:
 - 구현 전 실패해야 하는 테스트가 정의되어 있다.
- `reference/<model-id>/` artifact 요구사항이 명확하다.
- 최소 모델, benchmark 모델, 회귀 모델의 목적이 구분되어 있다.
+- 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다.
+- 필요한 source ID/component matching과 tolerance가 정의되어 있다.

 ### Gate 4: 구현 검증
 통과 조건:
@@ -312,9 +324,10 @@ flowchart TD

 ### Gate 5: 레퍼런스 검증
 통과 조건:
- Abaqus reference CSV 결과와 구현 solver HDF5 결과가 tolerance 안에 있다.
- 절점 변위, 반력, 요소 내력, 응력 비교 결과가 리포트로 남아 있다.
- 실패한 물리량이 없거나 승인된 known limitation으로 기록되어 있다.
+- 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가
+  tolerance 안에 있다.
+- 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다.