# Step 4: io-reference-contract

## Read These Files First

Read the following files before editing:

- `/AGENTS.md`
- `/docs/PRD.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/requirements/euler-beam-3d.md`
- `/docs/formulations/euler-beam-3d-formulation.md`
- `/docs/numerical-reviews/euler-beam-3d-review.md`
- `/docs/io-definitions/README.md`
- `/docs/reference-models/README.md`

## Task

Create two documents:

- `/docs/io-definitions/euler-beam-3d-io.md`
- `/docs/reference-models/euler-beam-3d-reference-models.md`

The I/O contract must describe the planned Abaqus subset without claiming it is implemented in this kernel increment:

- element keyword mapping candidate: two-node beam topology equivalent to Abaqus `B31`
- section keyword candidate: beam section constants sufficient for `A`, `J`, `Iy`, `Iz`, `E`, and `G`
- orientation data requirement for constructing local axes
- boundary/load DOFs: `1..6` map to `ux, uy, uz, rx, ry, rz`
- HDF5 output quantities expected after solver integration: nodal displacement, reaction, element internal force, stress placeholders if stress recovery is later approved
- unsupported input cases and diagnostics

The reference model contract must list required future models without generating artifacts:

- axial cantilever bar-as-beam
- torsion cantilever
- bending cantilever about local `y`
- bending cantilever about local `z`
- skew-oriented beam transform check

For each future model, specify expected files under `reference/<model-id>/` and which CSV quantities are required. State that Abaqus reference CSVs must not be generated or modified in this phase.

Do not create C++ files in this step.

## Tests To Write First

- No C++ test is required in this documentation-only step.

## Acceptance Criteria

```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```

## Verification Notes

1. Confirm reference artifacts are specified, not created.
2. Confirm unsupported parser or solver paths are explicit open issues.
3. Update `phases/euler-beam-3d/index.json` step 4:
   - success: `"status": "completed"`, `"summary": "3D Euler beam I/O and reference model contracts added"`
   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`

## Forbidden

- Do not create or modify files under `/reference/`.
- Do not modify source or tests.