Reference Verification Report 작성 가이드

Reference Verification Agent는 Build/Test 통과 뒤 FESA results.h5와 기능이 선언한 Abaqus CSV quantity를 비교한다. 비교 대상은 observable value이며 Abaqus 내부 formulation 동등성이 아니다.

기본 문서명은 docs/reference-verifications/<feature-id>-reference-verification.md다.

실행 순서

ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT

ARTIFACT CHECK는 다음만 요구한다.

declared .inp
generated FESA results.h5
every feature-required Abaqus CSV
HDF5 dataset projection
source-ID/component mapping
blocking/warning behavior
approved tolerance

Canonical naming, README, metadata, Abaqus version/provenance, duplicated units/coordinates/ step-frame fields와 reference CSV schema version은 기본 gate가 아니다.

Missing, extra, duplicate 또는 nonfinite required row는 tolerance 전에 실패한다. Row order alone으로 대응하지 않는다. FESA/Reference 값을 zero-clamp하거나 tolerance에 맞게 보정하지 않는다.

보고 항목

각 blocking 또는 warning-only quantity에 대해 다음을 보고한다.

exact input and CSV path
FESA HDF5 dataset
source ID/component mapping
compared, missing, extra, duplicate, nonfinite row counts
max absolute and relative error
RMS and norm error when required
worst source ID/component
pass, fail, or warning

Failure Classification

missing-reference-artifact: declared input or required CSV missing
missing-solver-output: results.h5 or comparison command missing
schema-mismatch: required source ID/component columns unavailable
id-mismatch: required source row sets do not match
tolerance-failure: blocking value exceeds approved tolerance
nonfinite-result: required FESA or reference value is not finite
upstream-contract: quantity, HDF5 projection, mapping, or tolerance missing/contradictory
environment: local comparison cannot run

문서 템플릿

# <Feature Title> Reference Verification Report

## Metadata
- feature_id: <feature-id>
- status: pass-for-physics-evaluation | needs-correction | needs-reference-artifacts | needs-solver-results | needs-upstream-decision | blocked
- owner_agent: reference-verification-agent
- date: <YYYY-MM-DD>

## Artifact Inventory
| item | path | status | notes |
| --- | --- | --- | --- |
| input | <exact path> | present | missing | <summary> |
| required_csv | <exact path> | present | missing | <summary> |
| solver_hdf5 | <path>/results.h5 | present | missing | <summary> |

## Comparison Contract
- hdf5_dataset: <path>
- source_id_mapping: <rule>
- components: <blocking/warning inventory>
- row_precheck: exact set; unique; finite
- tolerance_source: <path/requirement>
- tolerance_policy: <formula>

## Quantity Results
| quantity | components | behavior | compared | missing | extra | max_abs | max_rel | rms | norm | worst_id/component | result |
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |
| <quantity> | <components> | blocking | warning-only | <values> |

## Failure Classification
- classification: <value or N/A>
- evidence: <summary>

## Handoff Recommendation
- <target and exact evidence>

## No-Change Assertion
- source_files_modified: false
- test_files_modified: false
- cmake_files_modified: false
- reference_artifacts_modified: false
- tolerance_policies_modified: false

## Open Issues
- <only actual comparison blockers>

pass-for-physics-evaluation은 required blocking comparison 통과만 의미한다. Warning-only quantity는 경고를 남기되 verdict를 바꾸지 않는다. Physics validation과 release readiness는 각 후속 agent가 판정한다.