---
name: fesa-reference-comparison
description: Use when comparing FESA results.h5 quantities against feature-declared Abaqus CSV values or diagnosing reference tolerance, identity, row-set, or nonfinite-result failures.
---

# FESA Reference Comparison

Compare generated FESA HDF5 values with only the Abaqus CSV quantities declared by the feature.
The comparison tests observable values; it does not test Abaqus implementation equivalence.

## Inputs

Read these first:

- `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/reference-verifications/README.md`
- Build/Test report with `pass-for-reference-verification`
- `docs/reference-models/<feature-id>-reference-models.md`
- `docs/io-definitions/<feature-id>-io.md`
- Generated FESA `results.h5`
- Declared reference `.inp` and required Abaqus CSV files

## Workflow

1. Follow `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`.
2. ARTIFACT CHECK: verify the declared input, `results.h5`, every required CSV, HDF5
   projection, source-ID/component mapping, row prechecks, blocking/warning behavior, and tolerance.
3. Reject a missing input or required CSV as `needs-reference-artifacts`.
4. Reject a missing HDF5 result or comparison command as `needs-solver-results`.
5. Reject missing, extra, duplicate, or nonfinite required rows before tolerance evaluation.
6. COMPARE: normalize HDF5 values and match CSV values by declared source identity and component.
   Never match by row order alone.
7. Apply the upstream tolerance exactly. Do not clamp values, drop rows, loosen tolerance, or
   modify either artifact to obtain a pass.
8. Report per-row decisions, max absolute error, max relative error, RMS error, norm error when
   required, worst source ID/component, and pass/fail or warning per quantity.
9. CLASSIFY failures as missing-reference-artifact, missing-solver-output, schema-mismatch,
   id-mismatch, tolerance-failure, nonfinite-result, upstream-contract, or environment.

Do not require canonical names, README, metadata, Abaqus version/provenance, duplicated CSV
units/coordinates/step-frame fields, or a reference CSV schema version unless the feature
requirements explicitly make one of them part of comparison acceptance.

## Output Contract

Produce or revise `docs/reference-verifications/<feature-id>-reference-verification.md` with:

- Metadata
- Artifact Inventory
- Comparison Contract
- Quantity Results
- Failure Classification
- Handoff Recommendation
- No-Change Assertion
- Open Issues

## Boundaries

- Do not edit source, tests, CMake, upstream contracts, reference artifacts, or tolerances.
- Do not run Abaqus, Nastran, or another reference solver.
- Do not generate or modify reference CSV files.
- Do not approve physics validation or release readiness.

## Quality Gate

- Every declared required row has a deterministic source-ID/component match.
- Missing/extra/duplicate/nonfinite required rows remain visible and fail before tolerance.
- Warning-only quantities never change the blocking pass/fail verdict.
- `pass-for-physics-evaluation` means required reference tolerance success only.
- FESA `results.h5` remains authoritative solver output; Abaqus CSV remains external reference data.

## Handoff

Send passing reports to Physics Evaluation Agent. Send implementation-owned mismatches to
Correction Agent, missing declared files to Reference Model Agent, and HDF5 projection or
identity-contract conflicts to I/O Definition Agent.