docs: simplify FESA reference validation policy

This commit is contained in:
KOKO\Mimi
2026-08-12 03:19:20 +09:00
parent 0e785154d4
commit 5c08f1cf83
6 changed files with 178 additions and 50 deletions
+35 -5
View File
@@ -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 이름을 사용한다.
- `metadata.json`은 선택 reference artifact다. 파일이 없어도 bundle을 불완전하다고 판정하지 않으며, 필수 provenance, units, coordinate system, step/frame, schema, tolerance 정보는 승인된 기능별 reference model contract에 기록한다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약과 일치하는지 확인한다.
- 승인된 B33 baseline은 예외적으로 `reference/cantilever beam/`의 기존 space-containing 파일명을 read-only legacy alias로 사용한다.
- reference case는 기능 문서가 지정한 기존 `.inp`와 실제 비교에 필요한 Abaqus CSV 경로를
그대로 사용한다. canonical 이름, legacy-alias 승인, bundle `README.md`, `metadata.json`,
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`이 존재하면 그 설정을 우선한다.