# Reference Case 문서 작성 가이드

이 디렉터리는 Reference Model Agent가 작성하는 기능별 lightweight reference-case
inventory를 보관한다. Abaqus는 외부 수치 reference이며 FESA의 formulation 또는 내부
동작 계약이 아니다.

기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md`다. Agent는 Abaqus
또는 다른 reference solver를 실행하지 않고 `reference/` 파일을 생성, 수정, rename,
repair 또는 normalize하지 않는다.

## 필수 내용

기능이 실제로 비교하는 case마다 다음만 기록한다.

- case id와 목적
- existing `.inp` exact path
- blocking 또는 warning-only quantity의 existing CSV exact path
- FESA HDF5 dataset
- source identity와 component mapping
- missing/extra/duplicate/nonfinite row precheck
- approved tolerance
- artifact presence/readability status

다음은 기본 readiness 조건이 아니다.

- canonical directory/file naming 또는 legacy-alias 승인
- bundle `README.md` 또는 `metadata.json`
- Abaqus version/generation provenance
- duplicated units, coordinates, model, step/frame, material, section, thickness, element type
- reference CSV schema version
- 비교하지 않는 quantity CSV
- 요구조건이 요청하지 않은 benchmark portfolio

단일 static step/final frame 기능은 input/CSV pair로 result state를 식별한다. Material,
section, loads, constraints와 source element type은 `.inp`에서 읽는다.

## 문서 템플릿

```markdown
# <Feature Title> Reference Cases

## Metadata
- feature_id: <feature-id>
- status: draft | needs-user-decision | needs-reference-artifacts | ready-for-implementation-planning | blocked
- owner_agent: reference-model-agent
- date: <YYYY-MM-DD>

## Reference Acceptance Scope
- blocking_quantities: [<quantity/components>]
- warning_only_quantities: [<quantity/components>]
- excluded_quantities: [<quantity/reason>]

## Reference Case Inventory

| case_id | purpose | input | required_csv | quantity | behavior | status |
| --- | --- | --- | --- | --- | --- | --- |
| <case> | <purpose> | reference/<dir>/<file>.inp | reference/<dir>/<file>.csv | <components> | blocking | warning-only | present | missing |

## HDF5-to-CSV Comparison Mapping

| case_id | hdf5_dataset | source_id | csv_id_column | components | row_precheck |
| --- | --- | --- | --- | --- | --- |
| <case> | <path> | <node/element source id> | <column> | <components> | exact set; unique; finite |

## Tolerance and Blocking/Warning Policy
- reference_scale: <formula>
- row_tolerance: <formula>
- zero_policy: no clamp
- blocking_behavior: <rule>
- warning_behavior: <rule>

## Readiness Checklist
- declared input exists and is readable
- every required CSV exists and is readable
- source identity and required components are deterministic
- row-set/nonfinite prechecks are defined
- tolerance and blocking/warning behavior are approved

## Open Issues and Downstream Handoff
- <only missing required files, matching, tolerance, or feature-owned decisions>
```

## 상태 규칙

- `ready-for-implementation-planning`: required input/CSV files, mapping, and tolerance are complete.
- `needs-reference-artifacts`: a declared input or required comparison CSV is missing.
- `needs-user-decision`: required quantity, mapping, or tolerance is undefined.
- `blocked`: no safe progress is possible without an external decision or state change.

Canonical naming, README, metadata, provenance, and unrequested portfolio coverage do not select
any failure status.