# Step 2: formulation-spec

## 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/research/euler-beam-3d-research.md`
- `/docs/formulations/README.md`

## Task

Create `/docs/formulations/euler-beam-3d-formulation.md`.

The formulation must define the implementation contract for the C++ kernel. Include:

- local coordinate system: local `x` from node 1 to node 2; local `y` from the user orientation vector projected normal to local `x`; local `z = x cross y`
- local DOF order: `[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]`
- section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`
- local 12x12 stiffness matrix terms for:
  - axial: `EA/L`
  - torsion: `GJ/L`
  - bending in local `x-y` using `EIz`
  - bending in local `x-z` using `EIy`
- transformation matrix convention and global stiffness equation `K_global = T^T K_local T`
- end-force recovery equation `f_local = K_local u_local`
- validation tolerances for unit tests, using deterministic double comparisons
- singular and invalid input handling:
  - zero or near-zero length throws `std::invalid_argument`
  - nonpositive `E`, `G`, `A`, `J`, `Iy`, or `Iz` throws `std::invalid_argument`
  - orientation vector parallel to beam axis throws `std::invalid_argument`

Use compact matrices and named scalar coefficients so the implementation step can transcribe directly.

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 the matrix is symmetric by construction.
2. Confirm local/global transformation convention is unambiguous.
3. Update `phases/euler-beam-3d/index.json` step 2:
   - success: `"status": "completed"`, `"summary": "3D Euler beam formulation contract added"`
   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`

## Forbidden

- Do not modify requirements, source, tests, or reference artifacts.