# Step 5: Reference Model Contract

## 담당 역할과 필수 스킬

- 담당 역할: `reference-model-agent`
- 필수 스킬: `fesa-reference-models`
- 스킬을 끝까지 읽고 artifact 설계와 artifact 생성의 경계를 준수하라.

## 읽어야 할 파일

- `/AGENTS.md`
- `/docs/SOLVER_AGENT_DESIGN.md`
- `/.codex/skills/fesa-numerical-review/SKILL.md`
- `/docs/linear-static-3d-euler-beam/requirements.md`
- `/docs/linear-static-3d-euler-beam/research.md`
- `/docs/linear-static-3d-euler-beam/formulation.md`
- `/docs/linear-static-3d-euler-beam/numerical-review.md`
- `/docs/linear-static-3d-euler-beam/io.md`
- `/docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md`
- `/reference/cantilever beam/cantilever beam.inp`
- `/reference/cantilever beam/cantilever beam displacements.csv`
- `/reference/cantilever beam/cantilever beam reactions.csv`
- `/reference/cantilever beam/cantilever beam elemental forces.csv`

## 작업

`docs/linear-static-3d-euler-beam/reference-model.md`를 생성하라.
Metadata status는 `ready-for-implementation-planning`으로 둔다.

- code verification, analytical solution verification, B33 reference comparison을 분리한다.
- analytical inventory에 axial, torsion, local y/z bending, rotated beam, nonzero prescribed
  displacement, invalid input cases를 포함하고 각 target quantity/test를 연결한다.
- 승인 reference record는 `model_id: cantilever-beam-b33`, logical schema
  `abaqus-cae-report-csv-v0`, source commit `2b34d0b`, generator
  `Abaqus/CAE Learning Edition 2024`, SI, `Step-1`, increment 1/time 1.0을 기록한다.
- exact legacy paths 네 개를 inventory에 기록하고 B33 element type, expected header,
  unique row key, finite value artifact check를 요구한다.
- `metadata.json` 부재는 프로젝트 전역 선택-artifact 정책에 따라 허용하고, 이 legacy
  bundle에 한해서 `README.md`와 stress CSV가 N/A임을 명시한다. 설계와 이 contract가
  provenance/schema/tolerance/stress 사유를 기록한다.
- 이후 reference model에는 canonical file names와 `README.md`를 요구한다.
  `metadata.json`이 존재하면 read-only로 contract와 대조한다.
- displacement, reaction, section resultant coverage와 HDF5 dataset/CSV/component/tolerance를
  연결하는 Coverage Matrix를 작성한다. Stress comparison은 N/A지만 output unit/analytical
  verification을 연결한다.
- artifact 상태를 실제 파일 inventory에 따라 기록하되 reference 값을 재계산하지 않는다.

## Acceptance Criteria

```powershell
$path = 'docs/linear-static-3d-euler-beam/reference-model.md'
if (-not (Test-Path $path)) { throw "Missing $path" }
$artifacts = @(
  'reference/cantilever beam/cantilever beam.inp',
  'reference/cantilever beam/cantilever beam displacements.csv',
  'reference/cantilever beam/cantilever beam reactions.csv',
  'reference/cantilever beam/cantilever beam elemental forces.csv'
)
foreach ($artifact in $artifacts) {
  if (-not (Test-Path $artifact)) { throw "Missing approved artifact: $artifact" }
  if (-not (Select-String -LiteralPath $path -SimpleMatch $artifact -Quiet)) {
    throw "Artifact is not inventoried: $artifact"
  }
}
$required = @('status: `ready-for-implementation-planning`', 'cantilever-beam-b33',
  '2b34d0b', 'abaqus-cae-report-csv-v0', 'stress', 'N/A', '## Coverage Matrix')
foreach ($text in $required) {
  if (-not (Select-String -LiteralPath $path -SimpleMatch $text -Quiet)) {
    throw "Missing reference contract: $text"
  }
}
git diff --check -- $path
git diff --exit-code -- reference/
```

## 검증 절차

1. Acceptance Criteria 명령을 실행한다.
2. 네 legacy artifact가 exact path로만 참조되고 rename 제안이 없는지 확인한다.
3. 모든 must requirement가 model/test/quantity 또는 명시적 N/A에 연결되는지 확인한다.
4. Step 5를 `completed`와 inventory summary로 갱신한다. artifact 필수 조건 불충족은
   승인된 legacy 예외를 먼저 적용한 뒤 실제 결함만 `blocked`로 기록한다.

## 금지사항

- Abaqus나 다른 reference solver를 실행하지 마라. 이유: 이 step은 계약만 준비한다.
- `/reference/` 아래 어떤 파일도 생성·수정·rename하지 마라. 이유: baseline은 read-only다.
- legacy bundle에 metadata/README/stress CSV를 요구해 차단하지 마라. 이유: 승인된 예외다.
- reference comparison을 수행하거나 pass를 선언하지 마라. 이유: solver result가 아직 없다.
- 직접 commit하지 마라. 이유: Harness executor가 담당한다.