FESADev/docs/releases/README.md

# Release Report 문서 작성 가이드

이 디렉터리는 Release Agent가 작성하거나 제안하는 기능별 release readiness report를 보관하는 위치다.

Release Agent는 Physics Evaluation Agent가 `pass-for-release-agent`로 넘긴 기능에 대해 최종 gate evidence를 감사한다. 이 Agent는 source code, tests, CMake, upstream 계약, reference artifacts, tolerance policies를 수정하지 않는다. 또한 Abaqus/Nastran 실행, reference CSV 생성, 외부 publish/deploy/package/tag/commit 작업을 수행하지 않는다.

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

## Release Agent 역할

수행한다:
- upstream gate report가 같은 `feature_id`를 대상으로 하는지 확인한다.
- Build/Test report의 `pass-for-reference-verification` 상태를 확인한다.
- Reference Verification report의 `pass-for-physics-evaluation` 상태를 확인한다.
- Physics Evaluation report의 `pass-for-release-agent` 상태를 확인한다.
- 모든 `must` requirement가 acceptance criterion, test/reference evidence, release scope에 trace되는지 확인한다.
- known limitations, deferred issues, unsupported Abaqus keyword, accepted risks를 release note에 기록한다.
- release checklist와 Release Notes Draft를 작성한다.

수행하지 않는다:
- source code를 수정하지 않는다.
- tests를 수정하지 않는다.
- CMake files 또는 build configuration을 수정하지 않는다.
- requirements, formulations, I/O contracts, numerical review reports, reference verification reports, physics evaluation reports를 수정하지 않는다.
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
- reference CSV를 생성하지 않는다.
- 실패하거나 누락된 upstream gate를 우회하지 않는다.
- 사용자 명시 요청 없이 publish, deploy, package, tag, commit, external release를 수행하지 않는다.

## 실행 순서

Release Agent는 다음 순서를 따른다.

```text
GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
```

`GATE AUDIT`에서는 다음 evidence를 확인한다.

- Physics Evaluation report status: `pass-for-release-agent`
- Reference Verification report status: `pass-for-physics-evaluation`
- Build/Test report status: `pass-for-reference-verification`
- Implementation report와 implementation plan의 feature scope 일치
- requirements, formulations, numerical reviews, I/O definitions, reference models 문서의 feature scope 일치
- validation command evidence: `python scripts/validate_workspace.py`

## 문서 템플릿

```markdown
# <feature title> Release Report

## Metadata
- feature_id: <feature-id>
- source_requirement: docs/requirements/<feature-id>.md
- source_formulation: docs/formulations/<feature-id>-formulation.md
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
- source_io_definition: docs/io-definitions/<feature-id>-io.md
- source_reference_model: docs/reference-models/<feature-id>-reference-models.md
- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
- source_build_test_report: docs/build-test-reports/<feature-id>-build-test.md
- source_reference_verification_report: docs/reference-verifications/<feature-id>-reference-verification.md
- source_physics_evaluation_report: docs/physics-evaluations/<feature-id>-physics-evaluation.md
- status: ready-for-release | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-documentation | needs-upstream-decision | blocked
- owner_agent: release-agent
- date: <YYYY-MM-DD>

## Release Scope

| item | included | excluded | notes |
| --- | --- | --- | --- |
| analysis_type | <supported analysis> | <unsupported analysis> | <notes> |
| element_type | <supported elements> | <unsupported elements> | <notes> |
| material_model | <supported materials> | <unsupported materials> | <notes> |
| Abaqus input subset | <supported keywords> | <unsupported keywords> | <notes> |
| output_quantities | <supported outputs> | <unsupported outputs> | <notes> |

## Gate Evidence Inventory

| gate | source | expected_status | observed_status | verdict |
| --- | --- | --- | --- | --- |
| requirements | docs/requirements/<feature-id>.md | approved or release-ready | <status> | pass | fail | missing |
| formulation | docs/formulations/<feature-id>-formulation.md | reviewed | <status> | pass | fail | missing |
| numerical_review | docs/numerical-reviews/<feature-id>-review.md | pass-for-implementation-planning | <status> | pass | fail | missing |
| io_definition | docs/io-definitions/<feature-id>-io.md | ready | <status> | pass | fail | missing |
| reference_model | docs/reference-models/<feature-id>-reference-models.md | ready or artifacts present | <status> | pass | fail | missing |
| implementation | <implementation report> | implemented | <status> | pass | fail | missing |
| build_test | docs/build-test-reports/<feature-id>-build-test.md | pass-for-reference-verification | <status> | pass | fail | missing |
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <status> | pass | fail | missing |
| physics_evaluation | docs/physics-evaluations/<feature-id>-physics-evaluation.md | pass-for-release-agent | <status> | pass | fail | missing |

## Acceptance Traceability

| requirement_id | acceptance_criterion | test_id | reference_model_id | verification_report | release_disposition |
| --- | --- | --- | --- | --- | --- |
| <req-id> | <criterion> | <test-id> | <model-id> | <report path> | released | deferred | blocked |

## Validation Evidence

| command_or_report | expected | observed | notes |
| --- | --- | --- | --- |
| python scripts/validate_workspace.py | pass | <result> | <summary> |
| CMake/MSVC/CTest | pass | <result> | <summary> |
| reference verification | pass-for-physics-evaluation | <status> | <summary> |
| physics evaluation | pass-for-release-agent | <status> | <summary> |

## Known Limitations

| limitation | category | user_impact | disposition |
| --- | --- | --- | --- |
| <unsupported Abaqus keyword or solver scope limit> | input | physics | numerical | output | <impact> | documented | deferred | blocker |

## Release Notes Draft

### Feature Summary
- <user-facing summary>

### Verification Scope
- <validated analysis, element, material, I/O, reference model scope>

### Main Limitations
- <known limitation>

### Artifacts
- <release report, reference bundle, verification report paths>

## Release Verdict
- verdict: ready-for-release | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-documentation | needs-upstream-decision | blocked
- reason: <short reason>

## Handoff Recommendation

| target_agent | reason | required_input |
| --- | --- | --- |
| Coordinator Agent | <release decision or blocked issue> | <summary> |
| Correction Agent | <implementation-owned release blocker> | <failure evidence> |
| Reference Verification Agent | <missing or failed reference comparison> | <artifact and report gap> |
| Physics Evaluation Agent | <missing or failed physics evaluation> | <reference verification evidence> |
| Requirement Agent | <requirement or acceptance gap> | <open decision> |
| I/O Definition Agent | <I/O scope or Abaqus keyword limitation gap> | <contract gap> |
| Reference Model Agent | <reference artifact or coverage gap> | <model gap> |

## 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 evidence, contradictory upstream report, unresolved defect, incomplete reference artifact, or documentation gap>
```

## 상태 값

- `ready-for-release`: required gate가 모두 통과했고, 모든 `must` requirement traceability와 known limitations 문서화가 완료되었다.
- `needs-correction`: implementation-owned defect 또는 unresolved test/build/reference/physics issue가 있어 Correction Agent가 필요하다.
- `needs-reference-verification`: reference verification report가 없거나 `pass-for-physics-evaluation`이 아니다.
- `needs-physics-evaluation`: physics evaluation report가 없거나 `pass-for-release-agent`가 아니다.
- `needs-documentation`: gate evidence는 통과했지만 release scope, known limitations, release notes, traceability 문서가 불완전하다.
- `needs-upstream-decision`: requirement, tolerance, reference artifact, I/O, acceptance evidence가 누락되었거나 상충한다.
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.

## 품질 기준

- `ready-for-release`는 Build/Test, Reference Verification, Physics Evaluation gate evidence가 모두 present and passing일 때만 사용할 수 있다.
- 모든 `must` requirement는 acceptance criterion, test/reference evidence, release scope에 trace되어야 한다.
- known limitations와 deferred/open issue는 Release Notes Draft에 명확히 기록되어야 한다.
- missing evidence, contradictory upstream reports, unresolved defects, incomplete reference artifacts는 release pass가 아니라 적절한 `needs-*` 상태로 분류한다.
- 이 문서는 FESA 내부 feature release readiness 판정을 위한 것이며, 외부 publish/deploy/package/tag/commit 자동화는 포함하지 않는다.