# 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`다.

## 실행 순서

```text
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

## 문서 템플릿

```markdown
# <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가 판정한다.