# Step 9: reference-displacement-comparator

## Sprint Contract

### Objective
Implement the `references/*_displacements.csv` loader and comparator for FESA `U` output.

### Required Reading
- /AGENTS.md
- /PROGRESS.md
- /PLAN.md
- /docs/README.md
- /docs/HARNESS_ENGINEERING.md
- /docs/NUMERICAL_CONVENTIONS.md
- /docs/VERIFICATION_PLAN.md
- /docs/RESULTS_SCHEMA.md
- /references/README.md
- /phases/1-linear-static-mitc4/step8.md

### Scope
- Load Abaqus displacement CSV files with columns `Node Label`, `U-U1`, `U-U2`, `U-U3`, `UR-UR1`, `UR-UR2`, `UR-UR3`.
- Compare by node id, not row order.
- Implement absolute and relative tolerance behavior with a documented default or configuration path.
- Report missing columns, duplicate nodes, missing nodes, nonnumeric values, and tolerance failures.

### Allowed Files
- `include/**`
- `src/**`
- `tests/**`
- `references/**` only for small test fixtures or documentation updates
- `docs/VERIFICATION_PLAN.md` only for comparator tolerance clarification
- `docs/RESULTS_SCHEMA.md` only for schema clarification
- `PLAN.md`
- `PROGRESS.md`
- `phases/1-linear-static-mitc4/index.json`

### Explicit Non-Goals
- Do not require Abaqus execution.
- Do not treat `references/quad_01.inp` as Phase 1 supported input.
- Do not compare RF here unless a `*_reactions.csv` contract is added.

### Tests To Write First
- CSV header validation tests.
- Node-id matching and row-order independence tests.
- Absolute/relative tolerance pass/fail tests.
- Duplicate, missing, and malformed value diagnostics tests.
- Format-only smoke test using `references/quad_01_displacements.csv` if stable enough for CI.

### Reference Artifacts
- Format-only: `references/quad_01_displacements.csv`.
- Required later for solver regression: at least one Phase 1-compatible `TYPE=S4` input and matching displacement CSV.

### Acceptance Commands
```bash
python scripts/validate_workspace.py
```

### Evaluator Checklist
- Component mapping matches `docs/VERIFICATION_PLAN.md` and `docs/RESULTS_SCHEMA.md`.
- Comparison is by node id and independent of row order.
- Missing or malformed reference data fails with actionable diagnostics.
- `quad_01` is not used to imply S4R or nonlinear support.

### Handoff Requirements
- Record comparator behavior, tolerance decision, and validation in `PROGRESS.md`.
- Update `PLAN.md` if R-009 or reference artifact blockers change.
- Update the matching phase index entry: use `completed` with a one-line `summary`, or `blocked` with `blocked_reason`, or `error` with `error_message`.

## Verification
1. Run the acceptance command.
2. Inspect comparator tests for tolerance and malformed CSV behavior.

## Do Not
- Do not silently skip reference nodes or components.