# Physics Evaluation Report 문서 작성 가이드

이 디렉터리는 Physics Evaluation Agent가 작성하거나 제안하는 기능별 physics evaluation report를 보관하는 위치다.

Physics Evaluation Agent는 Reference Verification Agent가 `pass-for-physics-evaluation`로 넘긴 결과에 대해 물리적 타당성을 검토한다. 이 agent는 reference tolerance를 다시 판정하지 않고, HDF5 결과와 deterministic CSV views를 읽기 전용 evidence로 사용해 평형, 반력 부호, 변위 방향, 대칭성, 요소내력/응력 위치, rigid body mode 징후, energy/residual sanity, 테스트 모델 coverage를 검토한다.

기본 문서명은 `docs/physics-evaluations/<feature-id>-physics-evaluation.md` 형식을 사용한다.

## Physics Evaluation Agent 역할

수행한다:
- Reference Verification report가 `pass-for-physics-evaluation`인지 확인한다.
- documented physical expectation이 있는 항목만 pass/fail로 판정한다.
- global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, energy/residual, model coverage를 검토한다.
- 물리 검토 실패를 equilibrium-failure, reaction-inconsistency, displacement-direction-failure, symmetry-failure, stress-location-failure, element-force-inconsistency, rigid-body-mode-suspected, nonfinite-result, model-coverage-gap, upstream-contract, environment로 분류한다.
- 실패 원인에 따라 Correction Agent, Reference Model Agent, Formulation Agent, I/O Definition Agent, Coordinator Agent로 handoff한다.
- 모든 물리 검토가 문서화된 기대값을 만족하면 Release Agent로 handoff한다.

수행하지 않는다:
- source code를 수정하지 않는다.
- tests를 수정하지 않는다.
- CMake files를 수정하지 않는다.
- requirements, formulations, I/O contracts, reference model contracts를 수정하지 않는다.
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
- reference HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
- reference tolerance를 다시 판정하지 않는다.
- release readiness를 승인하지 않는다.
- release notes 또는 final release checklist를 작성하지 않는다.

## 실행 순서

Physics Evaluation Agent는 다음 순서를 따른다.

```text
EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
```

`EVIDENCE CHECK`에서 다음 항목을 확인한다.

- Reference Verification report status가 `pass-for-physics-evaluation`인지 여부
- checked solver/reference HDF5 files
- checked deterministic CSV views
- compared quantities
- model purpose
- documented physical expectations
- sign convention
- units and coordinate system
- output location and component naming

## Physics Checks

- `global equilibrium`: 적용 하중, 반력, sign convention이 문서화된 경우 전체 힘/모멘트 평형을 검토한다.
- `reaction consistency`: constrained DOF와 reaction component가 경계조건과 일관적인지 검토한다.
- `displacement direction`: 하중 방향, 구속조건, 예상 변형 모드와 변위 부호/방향이 맞는지 검토한다.
- `symmetry`: symmetry, antisymmetry, expected zero component가 모델 목적과 일치하는지 검토한다.
- `element force balance`: element internal force가 외력/반력 균형 또는 부호 일관성을 만족하는지 검토한다.
- `stress/strain`: stress/strain 부호, component, coordinate system, output location이 모델 expectation과 일치하는지 검토한다.
- `rigid body mode`: 불완전 구속, 비정상적으로 큰 변위, near-zero stiffness 징후를 검토한다.
- `energy/residual`: `csv/energy_or_residual.csv` 또는 residual output이 있을 때 energy balance, residual trend, convergence sanity를 검토한다.
- `model coverage`: reference model이 claimed feature를 충분히 검증하는지 검토한다.

## Failure Classification

- `equilibrium-failure`: 전체 하중-반력 또는 모멘트 평형이 기대와 다르다.
- `reaction-inconsistency`: constrained DOF reaction이 boundary condition 또는 load path와 일관되지 않는다.
- `displacement-direction-failure`: 변위 방향 또는 부호가 하중/구속조건과 물리적으로 맞지 않는다.
- `symmetry-failure`: expected symmetry, antisymmetry, zero component가 깨졌다.
- `stress-location-failure`: stress/strain output location 또는 component 해석이 물리 expectation과 맞지 않는다.
- `element-force-inconsistency`: element internal force balance 또는 sign이 일관되지 않는다.
- `rigid-body-mode-suspected`: rigid body mode 또는 under-constrained model 징후가 있다.
- `nonfinite-result`: NaN 또는 infinite value가 있다.
- `model-coverage-gap`: reference model이 기능을 충분히 검증하지 못한다.
- `upstream-contract`: physical expectation, sign convention, unit, coordinate, output location 계약이 누락 또는 충돌한다.
- `environment`: 로컬 실행/읽기 환경 문제로 평가가 불가능하다.

## 문서 템플릿

```markdown
# <feature title> Physics Evaluation Report

## Metadata
- feature_id: <feature-id>
- source_reference_verification_report: docs/reference-verifications/<feature-id>-reference-verification.md
- source_reference_model: docs/reference-models/<feature-id>-reference-models.md
- source_requirement: docs/requirements/<feature-id>.md
- source_formulation: docs/formulations/<feature-id>-formulation.md
- status: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
- owner_agent: physics-evaluation-agent
- date: <YYYY-MM-DD>

## Input Evidence

| evidence | path_or_source | status | notes |
| --- | --- | --- | --- |
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <summary> |
| solver_hdf5 | <solver output directory>/results.h5 | present | missing | <summary> |
| solver_csv_views | <solver output directory>/csv/ | present | missing | <summary or N/A> |
| reference_hdf5 | references/<feature-id>/<model-id>/reference.h5 | present | missing | <summary> |
| reference_csv_views | references/<feature-id>/<model-id>/csv/ | present | missing | <summary> |
| model_purpose | docs/reference-models/<feature-id>-reference-models.md | documented | missing | <summary> |
| physical_expectations | <source docs> | documented | missing | <summary> |

## Physics Checks

| check | documented_expectation | observed_evidence | verdict | classification |
| --- | --- | --- | --- | --- |
| global equilibrium | <expected force/moment balance> | <observed> | pass | fail | skipped | equilibrium-failure |
| reaction consistency | <expected reaction behavior> | <observed> | pass | fail | skipped | reaction-inconsistency |
| displacement direction | <expected direction/sign> | <observed> | pass | fail | skipped | displacement-direction-failure |
| symmetry | <expected symmetry/zero components> | <observed> | pass | fail | skipped | symmetry-failure |
| element force balance | <expected element force relation> | <observed> | pass | fail | skipped | element-force-inconsistency |
| stress/strain sanity | <expected sign/location/component> | <observed> | pass | fail | skipped | stress-location-failure |
| rigid body mode | <expected constrained behavior> | <observed> | pass | fail | skipped | rigid-body-mode-suspected |
| energy/residual | <expected energy/residual sanity> | <observed> | pass | fail | skipped | upstream-contract |
| model coverage | <claimed feature coverage> | <observed> | pass | fail | skipped | model-coverage-gap |

## Failure Classification
- classification: equilibrium-failure | reaction-inconsistency | displacement-direction-failure | symmetry-failure | stress-location-failure | element-force-inconsistency | rigid-body-mode-suspected | nonfinite-result | model-coverage-gap | upstream-contract | environment | N/A
- primary_failure: <short summary>
- evidence: <short relevant evidence>

## Evaluation Verdict
- verdict: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
- reason: <short reason>

## Handoff Recommendation

| target_agent | reason | required_input |
| --- | --- | --- |
| Correction Agent | <implementation-owned physical failure> | <failed check and evidence> |
| Reference Model Agent | <model coverage or missing physical expectation issue> | <coverage gap> |
| Formulation Agent | <formulation or sign convention issue> | <failed physics check> |
| I/O Definition Agent | <output location/component/unit/coordinate ambiguity> | <contract gap> |
| Coordinator Agent | <blocked or repeated ambiguity> | <classification and open issue> |
| Release Agent | <all documented physics checks passed> | <evaluation report> |

## No-Change Assertion
- source_files_modified: false
- test_files_modified: false
- cmake_files_modified: false
- reference_artifacts_modified: false
- tolerance_policies_modified: false
- notes: <observed no-change evidence or exception>

## Open Issues
- <missing physical expectation, incomplete model coverage, contradictory sign convention, or unavailable energy/residual evidence>
```

## 상태 값

- `pass-for-release-agent`: documented physics checks가 통과했고 Release Agent가 release readiness를 평가할 수 있다.
- `needs-correction`: implementation-owned physical failure가 있어 Correction Agent가 필요하다.
- `needs-reference-model`: reference model coverage가 부족하거나 추가 physical expectation이 필요하다.
- `needs-formulation-review`: formulation 또는 numerical review 재검토가 필요하다.
- `needs-io-decision`: output location, component naming, sign convention, unit, coordinate mapping이 evaluation을 막는다.
- `needs-upstream-decision`: physical expectation, sign convention, model purpose, acceptance criterion이 누락 또는 충돌한다.
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.

## 품질 기준

- Reference Verification report가 `pass-for-physics-evaluation`이 아니면 physics pass를 판정하지 않는다.
- documented expectation이 없는 항목은 pass/fail로 판정하지 않고 `skipped`, `needs-upstream-decision`, 또는 `needs-reference-model`로 둔다.
- 평형 검토는 적용 하중, 반력, element/internal force sign convention이 문서화된 경우에만 수행한다.
- stress/strain 검토는 output location, component naming, coordinate system, units가 정의된 경우에만 수행한다.
- HDF5와 deterministic CSV views는 읽기 전용 evidence로만 사용한다.
- pass는 Release Agent로 넘길 수 있다는 뜻이며 release readiness 승인이 아니다.
- reference artifacts와 tolerance policies는 수정하지 않는다.