add agents

docs/SOLVER_SKILL_DESIGN.md

@@ -0,0 +1,232 @@
+# FESA Solver Development Skill 구성안
+
+## 목적
+
+이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 Codex skills 구성을 정의한다.
+
+Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 기술과 절차 단위다. 따라서 skill은 Agent와 1:1로 대응시키지 않고, solver 개발 과정에서 반복되는 공통 workflow를 압축해 구성한다.
+
+## 설계 원칙
+
+- Skill은 특정 Agent 전용 지시가 아니라 여러 Agent가 공유하는 반복 절차로 둔다.
+- Skill은 `SKILL.md` 기반의 project-local workflow로 시작한다.
+- Skill은 구현 세부사항보다 입력, 절차, 산출물, 금지사항, 검증 기준을 제공한다.
+- Abaqus/Nastran 실행과 reference CSV 생성은 skill 범위에 포함하지 않는다.
+- C++ 구현 관련 skill은 C++17, MSVC, CMake, CTest, TDD 기준을 따른다.
+- 모든 검증은 `python scripts/validate_workspace.py`를 기본 workspace validation 명령으로 둔다.
+
+## Skill 구성
+
+### 1. `fesa-feature-definition`
+
+요구조건 정의와 연구 질문 정리를 위한 skill이다.
+
+사용 Agent:
+- Requirement Agent
+- Research Agent
+- Coordinator Agent
+- Release Agent
+
+적용 개발 과정:
+- 1. 솔버 기능에 대한 요구조건 정의
+- 2. 책, 논문 등 연구자료 조사
+
+주요 기능:
+- 기능 요청을 검증 가능한 requirement baseline으로 정리한다.
+- `shall` 요구조건, acceptance criteria, verification matrix를 작성한다.
+- 필요한 연구 질문과 source gap을 정리한다.
+- 미확정 tolerance, 지원 범위, reference artifact 요구사항을 open issue로 남긴다.
+
+대표 산출물:
+- `docs/requirements/<feature-id>.md`
+- `docs/research/<feature-id>-research.md`
+- requirement verification matrix
+- downstream handoff questions
+
+금지사항:
+- FEM 정식화를 확정하지 않는다.
+- C++ 구현, Abaqus/Nastran 실행, reference CSV 생성을 하지 않는다.
+- 검증 불가능한 요구조건을 완료 상태로 두지 않는다.
+
+### 2. `fesa-fem-specification`
+
+FEM 정식화, 수치 검토, 입출력 계약을 구현 가능한 specification으로 정리하기 위한 skill이다.
+
+사용 Agent:
+- Formulation Agent
+- Numerical Review Agent
+- I/O Definition Agent
+- Implementation Planning Agent
+
+적용 개발 과정:
+- 3. 코드 구현을 위한 유한요소 정식화
+- 4. 솔버 입출력 데이터 정의
+
+주요 기능:
+- strong form, weak form, shape function, B matrix, element equations를 정리한다.
+- numerical integration, Jacobian, output recovery, numerical risk를 점검한다.
+- Abaqus `.inp` keyword subset과 internal model mapping을 정의한다.
+- result CSV schema와 units, coordinate system, component naming을 정리한다.
+
+대표 산출물:
+- `docs/formulations/<feature-id>-formulation.md`
+- `docs/numerical-reviews/<feature-id>-review.md`
+- `docs/io-definitions/<feature-id>-io.md`
+
+금지사항:
+- C++ API나 파일 구조를 확정하지 않는다.
+- parser 구현을 하지 않는다.
+- reference artifact나 tolerance policy를 임의로 만들지 않는다.
+
+### 3. `fesa-reference-validation`
+
+reference model 설계, stored Abaqus CSV 비교, physics sanity 평가를 위한 skill이다.
+
+사용 Agent:
+- Reference Model Agent
+- Reference Verification Agent
+- Physics Evaluation Agent
+- Coordinator Agent
+
+적용 개발 과정:
+- 5. TDD 방법 사용을 위한 개발 솔버와 reference solver 테스트모델 작성
+- 7. reference solver 결과와 구현 solver 결과 비교
+- 8. 결과 차이가 tolerance 범위 내에 들어오면 구현 완료
+
+주요 기능:
+- `references/<feature-id>/<model-id>/` artifact bundle 요구사항을 정의한다.
+- `model.inp`, `metadata.json`, `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv`를 기준 artifact로 둔다.
+- solver result CSV와 stored reference CSV를 schema, unit, coordinate, id matching, tolerance 기준으로 비교한다.
+- reference verification 통과 후 equilibrium, reaction consistency, displacement direction, stress/strain sanity, model coverage를 검토한다.
+
+대표 산출물:
+- `docs/reference-models/<feature-id>-reference-models.md`
+- `docs/reference-verifications/<feature-id>-reference-verification.md`
+- `docs/physics-evaluations/<feature-id>-physics-evaluation.md`
+
+금지사항:
+- Abaqus/Nastran 또는 reference solver를 실행하지 않는다.
+- reference CSV를 생성하거나 수정하지 않는다.
+- tolerance를 통과시키기 위해 solver output을 보정하지 않는다.
+- physics pass를 release readiness로 해석하지 않는다.
+
+### 4. `fesa-cpp-msvc-tdd`
+
+C++17/MSVC/CMake/CTest 기반 TDD 구현과 build/test 실패 분석을 위한 skill이다.
+
+사용 Agent:
+- Implementation Planning Agent
+- Implementation Agent
+- Build/Test Executor Agent
+- Correction Agent
+
+적용 개발 과정:
+- 6. 코드 구현
+
+주요 기능:
+- upstream specification을 TDD task와 CMake/CTest plan으로 변환한다.
+- `RED -> GREEN -> VERIFY` 순서로 C++ 구현을 진행한다.
+- C++ production 변경에는 관련 C++ test를 요구한다.
+- Build/Test 실패를 configure, compile, link, test, reference-comparison, harness, environment, upstream-contract로 분류한다.
+- implementation-owned failure만 최소 수정한다.
+
+대표 산출물:
+- `docs/implementation-plans/<feature-id>-implementation-plan.md`
+- implementation report
+- `docs/build-test-reports/<feature-id>-build-test.md`
+- `docs/corrections/<feature-id>-correction.md`
+
+기본 검증 명령:
+
+```bash
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+기본 CMake/MSVC 경로:
+
+```bash
+cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
+cmake --build build/msvc-debug --config Debug
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug
+```
+
+금지사항:
+- 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 변경하지 않는다.
+- Abaqus/Nastran을 실행하지 않는다.
+- release readiness를 승인하지 않는다.
+
+### 5. `fesa-release-coordination`
+
+전체 workflow gate, handoff, blocker, release readiness 정리를 위한 skill이다.
+
+사용 Agent:
+- Coordinator Agent
+- Release Agent
+
+적용 개발 과정:
+- 9. 솔버 기능 배포
+
+주요 기능:
+- feature별 workflow state를 audit한다.
+- 다음 Agent handoff package를 작성한다.
+- repeated failure, blocker, user decision을 기록한다.
+- release checklist, known limitations, release notes draft를 작성한다.
+- Build/Test, Reference Verification, Physics Evaluation, Release gate evidence를 확인한다.
+
+대표 산출물:
+- `docs/coordination/<feature-id>-coordination.md`
+- `docs/releases/<feature-id>-release.md`
+
+상태 전이 기준:
+- `ready-for-implementation`: Implementation Planning report가 준비되었을 때
+- `needs-reference-verification`: Build/Test report가 `pass-for-reference-verification`일 때
+- `needs-physics-evaluation`: Reference Verification report가 `pass-for-physics-evaluation`일 때
+- `needs-release`: Physics Evaluation report가 `pass-for-release-agent`일 때
+- `completed`: Release Agent report가 `ready-for-release`이고 final workflow closure가 기록되었을 때
+
+금지사항:
+- 다른 Agent가 소유한 기술 판정을 대체하지 않는다.
+- 실패하거나 누락된 gate evidence를 우회하지 않는다.
+- 사용자 명시 요청 없이 publish, deploy, package, tag, commit을 수행하지 않는다.
+
+## 개발 과정과 Skill 매핑
+
+| 개발 과정 | Skill |
+| --- | --- |
+| 1. 솔버 기능에 대한 요구조건 정의 | `fesa-feature-definition` |
+| 2. 책, 논문 등 연구자료 조사 | `fesa-feature-definition` |
+| 3. 코드 구현을 위한 유한요소 정식화 | `fesa-fem-specification` |
+| 4. 솔버 입출력 데이터 정의 | `fesa-fem-specification` |
+| 5. TDD 방법 사용을 위한 테스트모델 작성 | `fesa-reference-validation` |
+| 6. 코드 구현 | `fesa-cpp-msvc-tdd` |
+| 7. reference solver 결과와 구현 solver 결과 비교 | `fesa-reference-validation` |
+| 8. tolerance 범위 내 결과 차이 확인 | `fesa-reference-validation` |
+| 9. 솔버 기능 배포 | `fesa-release-coordination` |
+
+## Agent와 Skill 관계
+
+| Agent | 주로 사용하는 Skill |
+| --- | --- |
+| Coordinator Agent | `fesa-release-coordination`, `fesa-feature-definition`, `fesa-reference-validation` |
+| Requirement Agent | `fesa-feature-definition` |
+| Research Agent | `fesa-feature-definition` |
+| Formulation Agent | `fesa-fem-specification` |
+| Numerical Review Agent | `fesa-fem-specification` |
+| I/O Definition Agent | `fesa-fem-specification` |
+| Reference Model Agent | `fesa-reference-validation` |
+| Implementation Planning Agent | `fesa-fem-specification`, `fesa-cpp-msvc-tdd` |
+| Implementation Agent | `fesa-cpp-msvc-tdd` |
+| Build/Test Executor Agent | `fesa-cpp-msvc-tdd` |
+| Correction Agent | `fesa-cpp-msvc-tdd` |
+| Reference Verification Agent | `fesa-reference-validation` |
+| Physics Evaluation Agent | `fesa-reference-validation` |
+| Release Agent | `fesa-release-coordination`, `fesa-feature-definition` |
+
+## v1 구현 방침
+
+- 각 skill은 `.codex/skills/<skill-name>/SKILL.md`에 둔다.
+- v1에서는 `SKILL.md`만 작성하고, 별도 scripts, references, assets, plugin packaging은 만들지 않는다.
+- skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 실제 반복 절차와 checklist 중심으로 작성한다.
+- skill description은 Codex가 자동으로 고를 수 있도록 trigger 상황을 명확히 쓴다.
+- 추후 반복 사용 중 절차가 안정화되면 검증 스크립트나 reference template을 skill resource로 분리한다.

docs/build-test-reports/README.md

@@ -0,0 +1,143 @@
+# Build/Test Report 문서 작성 가이드
+
+이 디렉터리는 Build/Test Executor Agent가 작성하거나 제안하는 기능별 build/test 실행 리포트를 보관하는 위치다.
+
+Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 C++/MSVC/CMake/CTest 검증을 실행하고, 실패를 분류해 다음 agent로 handoff한다. 이 agent는 source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다. build artifacts와 test outputs는 `build/` 아래 생성될 수 있다.
+
+기본 문서명은 `docs/build-test-reports/<feature-id>-build-test.md` 형식을 사용한다.
+
+## Build/Test Executor Agent 역할
+
+수행한다:
+- `python scripts/validate_workspace.py`를 기본 검증 명령으로 실행한다.
+- implementation plan/report에 명시된 경우 harness self-test와 feature-specific CTest를 실행한다.
+- `HARNESS_VALIDATION_COMMANDS`, `CMakePresets.json`의 `msvc-debug`, 기본 CMake/MSVC x64 Debug 경로 중 어떤 검증 경로가 사용되었는지 기록한다.
+- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
+- command, exit code, duration, stdout/stderr tail, failed test name을 요약한다.
+- 실패 원인에 따라 Implementation Agent, Correction Agent, Reference Verification Agent, Implementation Planning Agent 중 handoff 대상을 제안한다.
+
+수행하지 않는다:
+- source code를 수정하지 않는다.
+- tests를 수정하지 않는다.
+- CMake files를 수정하지 않는다.
+- requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다.
+- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
+- 최종 reference verification report를 작성하지 않는다.
+
+## 실행 순서
+
+기본 순서는 implementation plan/report에 따라 다음 중 필요한 항목만 실행한다.
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+ctest -C Debug -R <feature-or-label>
+python scripts/validate_workspace.py
+```
+
+`scripts/validate_workspace.py`의 command discovery 우선순위는 다음과 같다.
+
+1. `HARNESS_VALIDATION_COMMANDS`
+2. `CMakePresets.json`의 `msvc-debug`
+3. 기본 CMake/MSVC x64 Debug 명령
+4. `CMakeLists.txt`가 없고 override도 없으면 안내 메시지와 함께 성공 종료
+
+기본 CMake/MSVC x64 Debug 명령은 다음과 같다.
+
+```powershell
+cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
+cmake --build build/msvc-debug --config Debug
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug
+```
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Build/Test Report
+
+## Metadata
+- feature_id: <feature-id>
+- source_implementation_report: <path or N/A>
+- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
+- status: pass-for-reference-verification | needs-correction | needs-environment-fix | needs-upstream-decision | blocked
+- owner_agent: build-test-executor-agent
+- date: <YYYY-MM-DD>
+
+## Execution Environment
+- os: <OS and version>
+- generator: Visual Studio 17 2022 | <observed generator>
+- platform: x64 | <observed platform>
+- config: Debug | <observed config>
+- build_dir: build/msvc-debug | <observed build dir>
+- active_override_env_vars: HARNESS_VALIDATION_COMMANDS | HARNESS_CMAKE_GENERATOR | HARNESS_CMAKE_PLATFORM | HARNESS_CMAKE_CONFIG | HARNESS_BUILD_DIR | none
+- command_discovery_path: HARNESS_VALIDATION_COMMANDS | CMakePresets.json msvc-debug | default CMake/MSVC x64 Debug | no-CMake informational success
+
+## Command Log Summary
+
+| order | command | exit_code | duration | stdout_stderr_tail |
+| --- | --- | --- | --- | --- |
+| 1 | python -m unittest discover -s scripts -p "test_*.py" | <code> | <duration> | <tail summary> |
+| 2 | ctest -C Debug -R <feature-or-label> | <code> | <duration> | <tail summary> |
+| 3 | python scripts/validate_workspace.py | <code> | <duration> | <tail summary> |
+
+## Validation Results
+
+| validation_stage | result | evidence |
+| --- | --- | --- |
+| harness self-test | pass | fail | skipped | <summary> |
+| configure | pass | fail | skipped | <summary> |
+| build | pass | fail | skipped | <summary> |
+| CTest | pass | fail | skipped | <summary> |
+| feature-specific tests | pass | fail | skipped | <summary> |
+
+## Failure Classification
+
+- classification: configure | compile | link | test | reference-comparison | harness | environment | upstream-contract | N/A
+- primary_failure: <short reason>
+- first_failed_command: <command or N/A>
+- evidence_tail: <short excerpt or summary>
+
+## Failed Test Inventory
+
+| test_name | label | command | failure_summary |
+| --- | --- | --- | --- |
+| <test name> | <label or N/A> | <command> | <summary> |
+
+## Handoff Recommendation
+
+| target_agent | reason | required_input |
+| --- | --- | --- |
+| Implementation Agent | <when implementation-owned failure is found> | <command log and failing test> |
+| Correction Agent | <when focused repair/rollback is needed> | <failure classification and changed files from implementation report> |
+| Reference Verification Agent | <when build/test passes and reference comparison report is next> | <passing command evidence> |
+| Implementation Planning Agent | <when plan/test contract is incomplete> | <missing or contradictory plan item> |
+
+## No-Change Assertion
+- source_files_modified: false
+- test_files_modified: false
+- cmake_files_modified: false
+- reference_artifacts_modified: false
+- notes: <observed no-change evidence or exception>
+
+## Open Issues
+- <environment gap, missing CMake preset, missing reference artifact, repeated failure, or upstream-contract issue>
+```
+
+## 상태 값
+
+- `pass-for-reference-verification`: build/test 검증이 통과해 Reference Verification Agent로 넘길 수 있다.
+- `needs-correction`: compile, link, ordinary test, implementation-owned failure가 있어 Correction Agent 또는 Implementation Agent 작업이 필요하다.
+- `needs-environment-fix`: MSVC, CMake generator, Python, path, permission 등 로컬 환경 문제로 검증이 막혔다.
+- `needs-upstream-decision`: implementation plan, requirements, formulation, I/O, reference artifact, tolerance policy가 불완전하거나 충돌한다.
+- `blocked`: 반복 실패 또는 외부 조건 때문에 사용자나 Coordinator Agent 결정 없이는 진행할 수 없다.
+
+## 품질 기준
+
+- 모든 실행 명령과 exit code를 기록해야 한다.
+- 실패 로그는 전체 원문을 복제하지 않고 마지막 핵심 구간과 실패 원인을 요약한다.
+- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
+- no-CMake 상황은 `scripts/validate_workspace.py` 정책대로 안내 메시지와 성공 종료로 기록한다.
+- 성공 판정은 build/test 통과까지만 의미한다.
+- reference tolerance, physics validation, release readiness는 판정하지 않는다.
+- upstream 계약 문제는 Implementation Agent에 임의 수정으로 넘기지 않고 적절한 upstream agent로 handoff한다.

docs/coordination/README.md

@@ -0,0 +1,189 @@
+# Coordination Report 문서 작성 가이드
+
+이 디렉터리는 Coordinator Agent가 작성하거나 제안하는 기능별 workflow coordination report를 보관하는 위치다.
+
+Coordinator Agent는 FESA solver 기능 개발의 전체 lifecycle에서 gate evidence, handoff, rework loop, blocker, user decision을 관리한다. 이 Agent는 specialist agent의 기술 판정을 대체하지 않고, 다음 agent가 어떤 입력으로 무엇을 산출해야 하는지 명확히 기록한다.
+
+기본 문서명은 `docs/coordination/<feature-id>-coordination.md` 형식을 사용한다.
+
+## Coordinator Agent 역할
+
+수행한다:
+- feature request를 `feature_id`, target capability, initial priority, expected first agent로 분류한다.
+- existing docs/reports/artifacts를 읽고 workflow state를 audit한다.
+- gate별 source evidence, missing evidence, contradictory evidence를 inventory로 만든다.
+- 다음 agent handoff package를 작성한다.
+- repeated failure와 blocker를 추적하고 escalation target을 정한다.
+- final workflow closure를 기록한다.
+
+수행하지 않는다:
+- source code를 수정하지 않는다.
+- tests를 수정하지 않는다.
+- CMake files 또는 build configuration을 수정하지 않는다.
+- build/test validation을 실행하지 않는다.
+- reference comparison을 실행하지 않는다.
+- physics evaluation을 실행하지 않는다.
+- requirements, formulations, I/O contracts, numerical review reports를 수정하지 않는다.
+- reference artifacts 또는 tolerance policies를 수정하지 않는다.
+- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- subagents를 자동 spawn하지 않는다.
+- release readiness를 독립적으로 승인하지 않는다.
+
+## 실행 순서
+
+Coordinator Agent는 다음 순서를 따른다.
+
+```text
+INTAKE -> STATE AUDIT -> GATE DECISION -> HANDOFF PACKAGE -> STATUS REPORT
+```
+
+`STATE AUDIT`에서는 다음 evidence를 확인한다.
+
+- Requirement Agent output
+- Research Agent output
+- Formulation Agent output
+- Numerical Review Agent output
+- I/O Definition Agent output
+- Reference Model Agent output
+- Implementation Planning Agent output
+- Implementation Agent report
+- Build/Test Executor Agent report
+- Correction Agent report
+- Reference Verification Agent report
+- Physics Evaluation Agent report
+- Release Agent report
+- validation command evidence: `python scripts/validate_workspace.py`
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Coordination Report
+
+## Metadata
+- feature_id: <feature-id>
+- status: intake | needs-requirements | needs-research | needs-formulation | needs-numerical-review | needs-io-definition | needs-reference-model | needs-implementation-plan | ready-for-implementation | needs-build-test | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-release | ready-for-release | completed | needs-user-decision | blocked
+- owner_agent: coordinator-agent
+- date: <YYYY-MM-DD>
+- source_docs: <docs/reports used>
+
+## Feature Request Summary
+- requested_feature: <short summary>
+- current_goal: <current coordination goal>
+- included_scope: <included scope>
+- excluded_scope: <excluded scope>
+- priority: <initial priority>
+
+## Current Workflow State
+
+| item | value | notes |
+| --- | --- | --- |
+| current_gate | <gate> | <notes> |
+| completed_outputs | <outputs> | <notes> |
+| missing_outputs | <outputs> | <notes> |
+| active_blockers | <blockers> | <notes> |
+| next_eligible_gate | <gate> | <notes> |
+
+## Gate Evidence Inventory
+
+| gate | owning_agent | expected_evidence | observed_evidence | status | notes |
+| --- | --- | --- | --- | --- | --- |
+| requirements | Requirement Agent | docs/requirements/<feature-id>.md | <path/status> | pass | fail | missing | <notes> |
+| research | Research Agent | docs/research/<feature-id>-research.md | <path/status> | pass | fail | missing | <notes> |
+| formulation | Formulation Agent | docs/formulations/<feature-id>-formulation.md | <path/status> | pass | fail | missing | <notes> |
+| numerical_review | Numerical Review Agent | docs/numerical-reviews/<feature-id>-review.md | <path/status> | pass | fail | missing | <notes> |
+| io_definition | I/O Definition Agent | docs/io-definitions/<feature-id>-io.md | <path/status> | pass | fail | missing | <notes> |
+| reference_model | Reference Model Agent | docs/reference-models/<feature-id>-reference-models.md | <path/status> | pass | fail | missing | <notes> |
+| implementation_planning | Implementation Planning Agent | docs/implementation-plans/<feature-id>-implementation-plan.md | <path/status> | pass | fail | missing | <notes> |
+| implementation | Implementation Agent | implementation report | <path/status> | pass | fail | missing | <notes> |
+| build_test | Build/Test Executor Agent | pass-for-reference-verification | <path/status> | pass | fail | missing | <notes> |
+| correction | Correction Agent | correction report when needed | <path/status> | pass | fail | missing | <notes> |
+| reference_verification | Reference Verification Agent | pass-for-physics-evaluation | <path/status> | pass | fail | missing | <notes> |
+| physics_evaluation | Physics Evaluation Agent | pass-for-release-agent | <path/status> | pass | fail | missing | <notes> |
+| release | Release Agent | ready-for-release | <path/status> | pass | fail | missing | <notes> |
+
+## Decision Log
+
+| date | decision_type | decision | source_evidence | rationale |
+| --- | --- | --- | --- | --- |
+| <YYYY-MM-DD> | gate transition | blocker | user decision | rework decision | <decision> | <path/status> | <reason> |
+
+## Next Agent Handoff
+
+| field | value |
+| --- | --- |
+| target_agent | <agent name> |
+| reason | <why this agent is next> |
+| required_inputs | <docs/reports/artifacts> |
+| expected_output | <expected report or artifact contract> |
+| acceptance_gate | <status or gate required after handoff> |
+| stop_condition | <when the agent should stop and hand back> |
+| missing_evidence | <missing inputs or decisions> |
+
+## Traceability Snapshot
+
+| requirement_id | gate | report | artifact | status | current_disposition |
+| --- | --- | --- | --- | --- | --- |
+| <req-id> | <gate> | <report path> | <artifact path> | <status> | <released | deferred | blocked | pending> |
+
+## Risk and Blocker Register
+
+| risk_or_blocker | category | owner | status | next_action |
+| --- | --- | --- | --- | --- |
+| <issue> | upstream ambiguity | repeated failure | reference artifact gap | environment blocker | <agent/user> | open | mitigated | blocked | <action> |
+
+## Rework Loop Control
+
+| failure_classification | correction_attempt_count | escalation_target | stop_condition | notes |
+| --- | --- | --- | --- | --- |
+| <classification> | <count> | <agent/user> | <condition> | <notes> |
+
+## 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
+- <unresolved user decision, missing evidence, contradictory report, or blocked transition>
+```
+
+## 상태 값
+
+- `intake`: 기능 요청은 들어왔지만 첫 handoff가 완료되지 않았다.
+- `needs-requirements`: Requirement Agent가 요구조건을 정의하거나 수정해야 한다.
+- `needs-research`: Research Agent가 source-backed research evidence를 제공하거나 수정해야 한다.
+- `needs-formulation`: Formulation Agent가 FEM 정식화를 작성하거나 수정해야 한다.
+- `needs-numerical-review`: Numerical Review Agent가 정식화를 검토하거나 재검토해야 한다.
+- `needs-io-definition`: I/O Definition Agent가 Abaqus input/output 계약을 정의하거나 수정해야 한다.
+- `needs-reference-model`: Reference Model Agent가 reference model artifacts를 정의하거나 수정해야 한다.
+- `needs-implementation-plan`: Implementation Planning Agent가 TDD implementation plan을 작성하거나 수정해야 한다.
+- `ready-for-implementation`: implementation plan이 준비되었고 downstream 구현을 막는 upstream gate가 없다.
+- `needs-build-test`: 구현 이후 독립 Build/Test Executor 검증이 필요하다.
+- `needs-correction`: implementation-owned failure가 있어 Correction Agent가 필요하다.
+- `needs-reference-verification`: Build/Test evidence가 `pass-for-reference-verification`이다.
+- `needs-physics-evaluation`: Reference Verification report가 `pass-for-physics-evaluation`이다.
+- `needs-release`: Physics Evaluation report가 `pass-for-release-agent`이다.
+- `ready-for-release`: Release Agent report가 `ready-for-release`이고 final closure 기록이 필요하다.
+- `completed`: Release Agent report가 `ready-for-release`이고 Coordinator가 final workflow closure를 기록했다.
+- `needs-user-decision`: 사용자 또는 project decision 없이는 안전하게 진행할 수 없다.
+- `blocked`: 사용자 결정, 환경 변경, upstream correction 없이는 진행할 수 없다.
+
+## Handoff 원칙
+
+- 다음 단계 handoff는 source evidence, missing evidence, expected output, acceptance gate, stop condition을 포함해야 한다.
+- specialist agent가 소유한 기술 판정을 Coordinator가 대체하지 않는다.
+- `ready-for-implementation`은 Implementation Planning report가 `ready-for-implementation`일 때만 가능하다.
+- `needs-reference-verification`은 Build/Test evidence가 `pass-for-reference-verification`일 때만 가능하다.
+- `needs-physics-evaluation`은 Reference Verification report가 `pass-for-physics-evaluation`일 때만 가능하다.
+- `needs-release`는 Physics Evaluation report가 `pass-for-release-agent`일 때만 가능하다.
+- `completed`는 Release Agent report가 `ready-for-release`이고 final workflow closure가 기록된 경우에만 가능하다.
+- 동일 failure classification이 두 번 이상 반복되거나 upstream 계약 변경이 필요하면 `needs-user-decision` 또는 `blocked`로 전환한다.
+
+## 검증 기준
+
+- Coordinator Agent config와 문서 템플릿 검증은 Python unittest로 수행한다.
+- workspace 검증은 `python scripts/validate_workspace.py`를 사용한다.
+- 현재 repository에 CMake 프로젝트가 없으면 harness 정책에 따라 no-CMake validation 경로가 성공으로 기록될 수 있다.

docs/corrections/README.md

@@ -0,0 +1,153 @@
+# Correction Report 문서 작성 가이드
+
+이 디렉터리는 Correction Agent가 작성하거나 제안하는 기능별 correction report를 보관하는 위치다.
+
+Correction Agent는 Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent가 전달한 실패를 triage하고, implementation-owned failure만 최소 수정으로 복구한다. 이 agent는 source, header, test, CMake 수정은 수행할 수 있지만 requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.
+
+기본 문서명은 `docs/corrections/<feature-id>-correction.md` 형식을 사용한다.
+
+## Correction Agent 역할
+
+수행한다:
+- 실패 로그와 implementation report를 읽고 failure classification을 먼저 확정한다.
+- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
+- implementation-owned failure에 한해 source/header/test/CMake를 최소 수정한다.
+- 수정 후 targeted command를 먼저 실행하고 `python scripts/validate_workspace.py`를 실행한다.
+- harness, hook, agent config 관련 수정에서는 `python -m unittest discover -s scripts -p "test_*.py"`도 실행한다.
+- 반복 실패 또는 upstream 계약 문제를 Coordinator Agent나 관련 upstream agent로 handoff한다.
+
+수행하지 않는다:
+- requirements를 수정하지 않는다.
+- formulations를 수정하지 않는다.
+- I/O contracts를 수정하지 않는다.
+- numerical review reports를 수정하지 않는다.
+- reference artifacts를 수정하지 않는다.
+- tolerance policies를 수정하지 않는다.
+- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
+- 최종 reference verification report 또는 physics validation report를 작성하지 않는다.
+
+## 실행 순서
+
+Correction Agent는 항상 다음 순서를 따른다.
+
+```text
+TRIAGE -> MINIMAL FIX -> VERIFY -> REPORT
+```
+
+기본 검증 명령은 다음과 같다.
+
+```powershell
+<targeted command that reproduced the failure>
+python scripts/validate_workspace.py
+python -m unittest discover -s scripts -p "test_*.py"
+```
+
+`python -m unittest discover -s scripts -p "test_*.py"`는 harness, hook, agent config, Python validation behavior가 correction 범위에 포함될 때 실행한다.
+
+## Failure Classification
+
+- `configure`: CMake configure, preset, generator, cache setup 실패
+- `compile`: C++ compilation 실패
+- `link`: linker, symbol resolution, target dependency 실패
+- `test`: CTest, unit, integration, parser/I/O, ordinary regression test 실패
+- `reference-comparison`: 저장된 reference artifact와 deterministic comparison 실패
+- `harness`: Python harness self-test, TDD guard, hook, validation script 실패
+- `environment`: MSVC, CMake, Python, path, permission, generator, local dependency 문제
+- `upstream-contract`: requirements, formulation, I/O, reference artifact, tolerance, implementation plan 불일치 또는 누락
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Correction Report
+
+## Metadata
+- feature_id: <feature-id>
+- source_failure_report: docs/build-test-reports/<feature-id>-build-test.md | <reference/physics report path>
+- source_implementation_report: <path or N/A>
+- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
+- status: corrected-for-build-test | corrected-for-reference-verification | needs-build-test-rerun | needs-environment-fix | needs-upstream-decision | blocked
+- owner_agent: correction-agent
+- date: <YYYY-MM-DD>
+
+## Failure Triage
+- classification: configure | compile | link | test | reference-comparison | harness | environment | upstream-contract
+- first_failed_command: <command>
+- failed_target_or_test: <target, test, label, or N/A>
+- evidence_tail: <short relevant tail, not full log>
+- triage_decision: implementation-owned | environment-owned | upstream-owned | blocked
+
+## Root Cause Summary
+- root_cause_type: implementation defect | test defect | CMake registration issue | environment issue | upstream-contract issue
+- summary: <short explanation>
+- why_minimal_fix_is_allowed: <contract or failure evidence>
+
+## Correction Scope
+
+| file | change_type | reason | in_scope |
+| --- | --- | --- | --- |
+| include/fesa/<module>/<file>.hpp | source/header | <reason> | true |
+| src/<module>/<file>.cpp | source | <reason> | true |
+| tests/<module>/<file>_test.cpp | test | <reason> | true |
+| CMakeLists.txt | CMake | <reason> | true |
+
+Excluded files:
+- requirements: unchanged
+- formulations: unchanged
+- I/O contracts: unchanged
+- reference artifacts: unchanged
+- tolerance policies: unchanged
+
+## Verification Evidence
+
+| order | command | exit_code | result | evidence |
+| --- | --- | --- | --- | --- |
+| 1 | <targeted command> | <code> | pass | fail | <summary> |
+| 2 | python scripts/validate_workspace.py | <code> | pass | fail | <summary> |
+| 3 | python -m unittest discover -s scripts -p "test_*.py" | <code or skipped> | pass | fail | skipped | <summary> |
+
+## Traceability
+
+| requirement_id | task_id | test_id | failing_command | corrected_file | acceptance_criterion |
+| --- | --- | --- | --- | --- | --- |
+| <req-id or N/A> | <task-id or N/A> | <test-id or N/A> | <command> | <file> | <criterion> |
+
+## Handoff Recommendation
+
+| target_agent | reason | required_input |
+| --- | --- | --- |
+| Build/Test Executor Agent | <independent full validation required> | <commands and correction summary> |
+| Reference Verification Agent | <reference comparison rerun required> | <corrected-for-reference-verification evidence> |
+| Physics Evaluation Agent | <physics sanity rerun required> | <corrected solver behavior evidence> |
+| Implementation Agent | <new implementation task required> | <unfixed implementation gap> |
+| upstream agent | <contract issue> | <required upstream decision> |
+| Coordinator Agent | <repeated failure or blocked state> | <classification history and stop condition> |
+
+## Stop Condition
+- repeated_failure: true | false
+- upstream_ambiguity: true | false
+- reference_artifact_gap: true | false
+- environment_blocker: true | false
+- next_required_decision: <decision or N/A>
+```
+
+## 상태 값
+
+- `corrected-for-build-test`: correction이 Build/Test Executor Agent 재실행 단계로 넘어갈 수 있다.
+- `corrected-for-reference-verification`: correction이 Reference Verification Agent 재실행 단계로 넘어갈 수 있다.
+- `needs-build-test-rerun`: targeted correction은 통과했지만 독립 build/test 재실행이 필요하다.
+- `needs-environment-fix`: 로컬 toolchain, generator, Python, path, permission 문제가 correction 또는 verification을 막는다.
+- `needs-upstream-decision`: upstream contract, reference artifact, tolerance, formulation ambiguity가 안전한 수정을 막는다.
+- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
+
+## 품질 기준
+
+- 수정 전 failure classification을 기록해야 한다.
+- 모든 변경은 실패 로그 또는 implementation plan acceptance criterion에 trace되어야 한다.
+- production C++ 수정에는 관련 테스트 또는 기존 실패 테스트가 있어야 한다.
+- requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.
+- 실패 로그는 전체 원문을 복제하지 않고 핵심 tail과 원인 요약만 기록한다.
+- 동일 classification이 두 번 반복되면 Coordinator Agent 또는 관련 upstream agent로 handoff한다.
+- 성공 판정은 correction verification까지만 의미한다.
+- release readiness, reference tolerance success, physics validation success는 판정하지 않는다.

docs/implementation-plans/README.md

@@ -0,0 +1,140 @@
+# Implementation Plan 문서 작성 가이드
+
+이 디렉터리는 Implementation Planning Agent가 작성하거나 제안한 기능별 구현계획 문서를 보관하는 위치다.
+
+Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의, reference model 계약을 C++/MSVC 구현 전 TDD 작업계획으로 변환한다. Agent는 코드, 테스트, CMake 파일을 작성하지 않고, Abaqus/Nastran을 실행하지 않으며, reference CSV 생성이나 solver 결과 비교, release readiness 승인도 하지 않는다.
+
+기본 파일명은 `docs/implementation-plans/<feature-id>-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다.
+
+## Implementation Planning Agent 역할
+
+수행한다:
+- upstream 문서가 구현 계획에 충분한지 Readiness Check를 수행한다.
+- 요구조건과 정식화를 작은 Work Breakdown task로 나눈다.
+- unit, integration, parser/I/O, reference-comparison 테스트를 TDD 순서로 정렬한다.
+- CMake/CTest target, `add_test`, label, `ctest -C Debug` 검증 계획을 정의한다.
+- candidate source/header/test/CMake 파일과 ownership boundary를 제안한다.
+- requirement, task, test, reference model, acceptance criterion을 Acceptance Traceability Matrix로 연결한다.
+- `python scripts/validate_workspace.py`를 포함한 validation command를 명시한다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- 테스트 파일을 작성하지 않는다.
+- CMake 파일을 수정하지 않는다.
+- CMake/CTest를 실행하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- solver 결과를 비교하지 않는다.
+- release readiness를 승인하지 않는다.
+- C++ API, class name, storage layout, file ownership을 확정하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Implementation Plan
+
+## Metadata
+- feature_id: <feature-id>
+- source_requirement: docs/requirements/<feature-id>.md
+- source_research: docs/research/<feature-id>-research.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_models: docs/reference-models/<feature-id>-reference-models.md
+- status: draft | needs-upstream-decision | ready-for-implementation | blocked
+- owner_agent: implementation-planning-agent
+- date: <YYYY-MM-DD>
+
+## Readiness Check
+
+| input | required_status | observed_status | decision |
+| --- | --- | --- | --- |
+| requirement | approved or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
+| formulation | pass-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
+| numerical_review | pass-for-implementation-planning | <status> | proceed | needs-upstream-decision | blocked |
+| io_definition | ready-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
+| reference_models | ready-for-implementation-planning or planned artifacts | <status> | proceed | needs-upstream-decision | blocked |
+
+## Implementation Scope
+- included_behavior: <behavior to implement>
+- excluded_behavior: <behavior explicitly out of scope>
+- non_goals: <items not to design or implement in this phase>
+
+## Work Breakdown
+
+| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
+| --- | --- | --- | --- | --- | --- |
+| TASK-001 | 1 | <small implementation task> | <requirement/formulation/io/reference id> | none | TEST-001 |
+
+## TDD Test Plan
+
+| test_id | order | test_type | red_condition | green_condition | linked_task | command |
+| --- | --- | --- | --- | --- | --- | --- |
+| TEST-001 | 1 | unit | test fails because behavior is missing | test passes after minimal implementation | TASK-001 | ctest -C Debug -R <test-name> |
+| TEST-002 | 2 | integration | integrated path fails before implementation | integrated path passes | TASK-002 | ctest -C Debug -R <test-name> |
+| TEST-003 | 3 | parser/I/O | Abaqus .inp case is not accepted or mapped | input maps to expected semantic model | TASK-003 | ctest -C Debug -R <test-name> |
+| TEST-004 | 4 | reference-comparison | solver CSV comparison fails before implementation | comparison is within planned tolerance | TASK-004 | ctest -C Debug -R <test-name> |
+
+## CMake/CTest Plan
+- target_candidates: <library/test executable targets>
+- add_test_needs: <CTest registration needs>
+- labels: unit | integration | reference | parser | io
+- msvc_config: Debug
+- expected_feature_command: ctest -C Debug -R <feature-or-label>
+- workspace_validation: python scripts/validate_workspace.py
+
+## Candidate Files and Ownership
+
+| file_candidate | purpose | owner_boundary | notes |
+| --- | --- | --- | --- |
+| include/fesa/<module>/<candidate>.hpp | <candidate public header role> | candidate only, not final API | <notes> |
+| src/<module>/<candidate>.cpp | <candidate implementation role> | candidate only, not final API | <notes> |
+| tests/<module>/<candidate>_test.cpp | <test role> | required before production change | <notes> |
+| CMakeLists.txt | <target/test registration role> | candidate only | <notes> |
+
+## Data Flow Contract
+1. Abaqus `.inp` input follows docs/io-definitions/<feature-id>-io.md.
+2. Parser/I/O path maps model data and history data into the internal semantic model.
+3. Solver path produces displacement, reaction, element force, stress, or feature-specific result CSV.
+4. Reference comparison tests compare solver CSV against `references/<feature-id>/<model-id>/` artifacts.
+
+## Acceptance Traceability Matrix
+
+| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
+| --- | --- | --- | --- | --- | --- |
+| <req-id> | TASK-001 | TEST-001 | <model-id or N/A> | <criterion> | draft |
+
+## Validation Commands
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest -C Debug -R <feature-or-label>
+```
+
+## Risks and Downstream Handoff
+
+### Implementation Agent
+- <task order, tests to write first, candidate files, acceptance criteria>
+
+### Build/Test Executor Agent
+- <validation commands, expected CTest labels, feature-specific commands>
+
+### Correction Agent
+- <likely failure classifications and upstream rollback guidance>
+
+### Reference Verification Agent
+- <planned CSV comparison tests, reference model ids, tolerance mapping, ID matching assumptions>
+
+## Open Issues
+- <requirement, formulation, I/O, reference artifact, tolerance, or architecture issue>
+```
+
+## 품질 기준
+
+- 모든 `must` requirement는 최소 하나의 task와 test에 연결되어야 한다.
+- C++ production 변경마다 선행 테스트 파일 또는 테스트 추가 계획이 있어야 한다.
+- reference artifact가 필요한 기능은 `references/<feature-id>/<model-id>/`와 CSV 비교 테스트 계획을 가져야 한다.
+- CMake/CTest 계획은 MSVC x64 Debug 검증 경로와 호환되어야 한다.
+- 구현 계획은 테스트 작성, 실패 확인, 최소 구현, validation 순서를 명시해야 한다.
+- upstream 문서가 불완전하면 값을 임의로 채우지 않고 `needs-upstream-decision` 또는 `blocked`로 표시한다.
+- release 완료나 reference tolerance 통과 판정은 하지 않는다.

docs/io-definitions/README.md

@@ -0,0 +1,180 @@
+# I/O 정의 문서 작성 가이드
+
+이 디렉터리는 I/O Definition Agent가 작성하거나 제안한 기능별 입출력 정의 문서를 보관하는 위치다.
+
+FESA 솔버의 입력 파일은 Abaqus input file이다. 다만 초기 FESA는 Abaqus 전체 문법 호환을 목표로 하지 않고, 기능별로 지원할 Abaqus keyword subset과 내부 모델 매핑을 명확히 정의한다.
+
+기본 파일명은 `docs/io-definitions/<feature-id>-io.md` 형식을 사용한다. 각 문서는 Requirement Agent, Formulation Agent, Numerical Review Agent의 산출물을 입력으로 받아 Abaqus `.inp` 입력 계약과 결과 CSV schema를 정의해야 한다.
+
+## I/O Definition Agent 역할
+
+I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, output request mapping, comparison CSV schema를 정의한다.
+
+수행한다:
+- 기능별 supported Abaqus keyword subset을 정의한다.
+- unsupported, ignored-with-warning, requires-user-decision keyword 정책을 정의한다.
+- model data와 history data를 내부 solver 개념으로 매핑한다.
+- node, element, set, material, section, boundary condition, load, step, output request의 의미 계약을 정의한다.
+- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` schema를 정의한다.
+
+수행하지 않는다:
+- parser를 구현하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- solver 결과와 reference 결과를 비교하지 않는다.
+- release readiness를 승인하지 않는다.
+- 명시적으로 정의되지 않은 Abaqus full compatibility를 주장하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> I/O Definition
+
+## 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_research: docs/research/<feature-id>-research.md
+- status: draft | needs-user-decision | ready-for-implementation-planning
+- owner_agent: io-definition-agent
+- date: <YYYY-MM-DD>
+
+## Abaqus Input Scope
+- input_format: Abaqus input file (`.inp`)
+- abaqus_documentation_source: <version/source URL>
+- compatibility_disclaimer: FESA supports only the keyword subset defined in this document.
+
+| keyword | support_status | level | required_parameters | mapped_internal_concept | notes |
+| --- | --- | --- | --- | --- | --- |
+| *HEADING | supported | model | N/A | model title | optional |
+| *INCLUDE | supported | model/history | INPUT | include file | path policy required |
+| *NODE | supported | model | N/A | node label and coordinates |  |
+| *NSET | supported | model | NSET | node set | sorted/unsorted policy required |
+| *ELEMENT | supported | model | TYPE | element label, type, connectivity |  |
+| *ELSET | supported | model | ELSET | element set |  |
+| *MATERIAL | supported | model | NAME | material |  |
+| *ELASTIC | supported | model | N/A or TYPE | elastic material data |  |
+| <section keyword> | supported | model | ELSET, MATERIAL | section assignment | e.g. *SOLID SECTION |
+| *BOUNDARY | supported | model/history | N/A | boundary condition |  |
+| *CLOAD | supported | history | N/A | concentrated load | feature-dependent |
+| *DLOAD | supported | history | N/A | distributed load | feature-dependent |
+| *STEP | supported | history | N/A | analysis step |  |
+| <procedure keyword> | supported | history | N/A | analysis procedure | e.g. *STATIC |
+| *OUTPUT | supported | history | N/A | output request root |  |
+| *NODE OUTPUT | supported | history | N/A | nodal output request |  |
+| *ELEMENT OUTPUT | supported | history | N/A | element output request |  |
+
+## Syntax Policy
+- case_insensitivity: <policy>
+- comma_separated_fields: <policy>
+- comment_lines: lines beginning with `**`
+- keyword_continuation: <policy>
+- include_files: <relative path policy>
+- labels: <case/quote/name policy>
+- line_length_limit: <policy>
+- ascii_assumption: <policy>
+- empty_data_fields: <policy>
+
+## Model Data Mapping
+- nodes: <node label, coordinate dimension, coordinate system>
+- elements: <element label, element type, connectivity>
+- node_sets: <set name, sorted/unsorted, expansion rules>
+- element_sets: <set name, expansion rules>
+- material: <material name and data>
+- section: <section assignment>
+- coordinates: <global/local coordinate conventions>
+- units: <unit system policy>
+
+## History Data Mapping
+- steps: <step naming and order>
+- procedure: <analysis procedure keyword mapping>
+- boundary_conditions: <boundary condition mapping>
+- loads: <load keyword mapping>
+- output_requests: <node/element output mapping>
+
+## Internal Model Contract
+- node_label: <semantic contract>
+- element_label: <semantic contract>
+- element_type: <semantic contract>
+- connectivity: <semantic contract>
+- set_membership: <semantic contract>
+- material: <semantic contract>
+- section: <semantic contract>
+- boundary_condition: <semantic contract>
+- load: <semantic contract>
+- step: <semantic contract>
+- output_request: <semantic contract>
+
+## Output and CSV Schemas
+
+### displacements.csv
+| column | type | description |
+| --- | --- | --- |
+| step | string | step name or index |
+| frame | integer | frame or increment id |
+| node_id | integer/string | Abaqus node label |
+| ux | float | displacement component |
+| uy | float | displacement component or 0/N/A |
+| uz | float | displacement component or 0/N/A |
+
+### reactions.csv
+| column | type | description |
+| --- | --- | --- |
+| step | string | step name or index |
+| frame | integer | frame or increment id |
+| node_id | integer/string | Abaqus node label |
+| rfx | float | reaction component |
+| rfy | float | reaction component or 0/N/A |
+| rfz | float | reaction component or 0/N/A |
+
+### element_forces.csv
+| column | type | description |
+| --- | --- | --- |
+| step | string | step name or index |
+| frame | integer | frame or increment id |
+| element_id | integer/string | Abaqus element label |
+| location | string | element/nodal/integration_point location |
+| component | string | force component name |
+| value | float | component value |
+
+### stresses.csv
+| column | type | description |
+| --- | --- | --- |
+| step | string | step name or index |
+| frame | integer | frame or increment id |
+| element_id | integer/string | Abaqus element label |
+| integration_point | integer/string | integration point id or N/A |
+| component | string | stress component name |
+| value | float | stress value |
+
+## Validation Rules
+- required_fields: <required input fields>
+- duplicate_labels: <policy>
+- missing_references: <policy>
+- unsupported_keywords: unsupported | ignored-with-warning | requires-user-decision
+- set_expansion: <policy>
+- coordinate_conventions: <policy>
+- output_quantity_availability: <policy>
+
+## Open Issues and Downstream Handoff
+
+### Reference Model Agent
+- <Abaqus input examples and reference artifact schema needs>
+
+### Implementation Planning Agent
+- <parser acceptance cases, unsupported keyword diagnostics, CSV writer tests>
+
+### Reference Verification Agent
+- <CSV schemas, ID matching rules, units, coordinate conventions, tolerance-relevant fields>
+```
+
+## 품질 기준
+
+- 입력 파일은 Abaqus `.inp`임을 명시해야 한다.
+- Abaqus full compatibility를 주장하지 않고 기능별 supported keyword subset을 명시해야 한다.
+- model data와 history data의 매핑을 구분해야 한다.
+- unsupported keyword 처리 정책을 명확히 해야 한다.
+- 내부 모델 계약은 semantic fields로 작성하고 C++ class/function/API를 확정하지 않는다.
+- CSV schema는 column name, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.

docs/numerical-reviews/README.md

@@ -0,0 +1,102 @@
+# 수치 검토 리포트 작성 가이드
+
+이 디렉터리는 Numerical Review Agent가 작성하거나 제안한 기능별 수치 검토 리포트를 보관하는 위치다.
+
+기본 파일명은 `docs/numerical-reviews/<feature-id>-review.md` 형식을 사용한다. 각 리포트는 Formulation Agent의 정식화 문서를 독립 검토해, 구현 계획 단계로 넘겨도 되는지 판단한다.
+
+## Numerical Review Agent 역할
+
+Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위험, 검증 준비 상태를 검토한다.
+
+수행한다:
+- 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
+- `B` matrix 또는 kinematic operator, constitutive contract, element equation을 검토한다.
+- rigid body modes, patch test, symmetry, positive definiteness를 확인한다.
+- hourglass, shear locking, volumetric locking, distortion, singular Jacobian, conditioning 위험을 식별한다.
+- 구현 계획 전에 필요한 정식화 수정, 연구 보강, reference model 요구사항을 작성한다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- 정식화 문서를 직접 수정하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- release readiness를 승인하지 않는다.
+- 레퍼런스 결과와 구현 솔버 결과의 일치 여부를 판정하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Numerical Review
+
+## Metadata
+- feature_id: <feature-id>
+- source_formulation: docs/formulations/<feature-id>-formulation.md
+- status: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
+- owner_agent: numerical-review-agent
+- date: <YYYY-MM-DD>
+
+## Review Verdict
+- verdict: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
+- reason: <판정 이유>
+
+## Critical Findings
+- <구현 전 반드시 수정할 수식 또는 수치 결함>
+
+## Numerical Risk Assessment
+- rigid_body_modes: <check/risk>
+- patch_test: <check/risk>
+- symmetry: <check/risk>
+- positive_definiteness: <check/risk>
+- hourglass: <check/risk or N/A>
+- shear_locking: <check/risk or N/A>
+- volumetric_locking: <check/risk or N/A>
+- distortion: <check/risk>
+- singular_jacobian: <check/risk>
+- conditioning: <check/risk>
+- convergence: <check/risk or N/A>
+
+## Consistency Checks
+- units: <pass/fail/TBD>
+- dimensions: <pass/fail/TBD>
+- signs: <pass/fail/TBD>
+- dof_ordering: <pass/fail/TBD>
+- coordinate_transforms: <pass/fail/TBD>
+- matrix_vector_dimensions: <pass/fail/TBD>
+- integration_weights: <pass/fail/TBD>
+- output_locations: <pass/fail/TBD>
+
+## Verification Readiness
+- unit_tests: <필요한 단위 테스트>
+- patch_tests: <필요한 patch test>
+- mms_or_mes: <MMS/MES 후보 또는 N/A>
+- benchmark_reference_comparison: <필요한 benchmark/reference 비교>
+- missing_evidence: <누락된 검증 근거>
+
+## Required Revisions
+
+### Formulation Agent
+- <정식화 수정 지시>
+
+### Research Agent
+- <연구 보강 지시>
+
+### Reference Model Agent
+- <reference model 또는 artifact 요구사항>
+
+## Downstream Handoff
+
+### Implementation Planning Agent
+- <테스트와 acceptance criteria로 변환할 항목>
+
+### Reference Model Agent
+- <테스트 모델로 변환할 항목>
+```
+
+## 품질 기준
+
+- 확인된 결함, 위험, open question을 구분해야 한다.
+- `pass-for-implementation-planning`은 구현 계획으로 넘겨도 된다는 뜻이며 기능 완료나 release 승인이 아니다.
+- 정식화 문서를 직접 수정하지 않고 필요한 수정을 명확히 지시해야 한다.
+- 모든 검토는 dimension, sign, DOF ordering, coordinate transform, Jacobian, integration weight, element equation, output recovery를 포함해야 한다.
+- numerical risk는 rigid body modes, patch test, symmetry, positive definiteness, hourglass, locking, singular Jacobian, conditioning을 포함해야 한다.

docs/physics-evaluations/README.md

@@ -0,0 +1,164 @@
+# Physics Evaluation Report 문서 작성 가이드
+
+이 디렉터리는 Physics Evaluation Agent가 작성하거나 제안하는 기능별 physics evaluation report를 보관하는 위치다.
+
+Physics Evaluation Agent는 Reference Verification Agent가 `pass-for-physics-evaluation`으로 넘긴 결과에 대해 물리적 타당성을 검토한다. 이 agent는 reference tolerance를 다시 판정하지 않고, 평형, 반력 부호/합력, 변위 방향, 대칭성, 요소내력/응력 위치, 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 CSV를 생성하지 않는다.
+- 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 CSVs
+- 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`: 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_results | <solver CSV path> | present | missing | <summary> |
+| reference_results | references/<feature-id>/<model-id>/ | 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가 정의된 경우에만 수행한다.
+- pass는 Release Agent로 넘길 수 있다는 뜻이며 release readiness 승인이 아니다.
+- reference artifacts와 tolerance policies는 수정하지 않는다.

docs/reference-models/README.md

@@ -0,0 +1,205 @@
+# Reference Model 문서 작성 가이드
+
+이 디렉터리는 Reference Model Agent가 작성하거나 제안한 기능별 reference model 설계 문서를 보관하는 위치다.
+
+Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않고, reference CSV 값을 생성하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.
+
+기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md` 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.
+
+## Reference Model Agent 역할
+
+수행한다:
+- 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
+- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
+- `references/<feature-id>/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
+- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
+- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` 요구사항을 정의한다.
+- requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- parser를 구현하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- solver 결과를 비교하지 않는다.
+- release readiness를 승인하지 않는다.
+- reference 값, tolerance, Abaqus compatibility를 임의로 만들지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Reference Models
+
+## Metadata
+- feature_id: <feature-id>
+- source_requirement: docs/requirements/<feature-id>.md
+- source_research: docs/research/<feature-id>-research.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
+- status: draft | needs-user-decision | needs-reference-artifacts | ready-for-implementation-planning | blocked
+- owner_agent: reference-model-agent
+- date: <YYYY-MM-DD>
+
+## Reference Strategy
+- verification_scope: <feature verification purpose>
+- code_verification: <unit/math-level checks supported by this portfolio>
+- solution_verification: <mesh, convergence, patch, or analytical checks>
+- benchmark_reference_comparison: <Abaqus/NAFEMS/NASA/paper-derived comparison plan>
+- excluded_validation_scope: <physical experiment validation excluded unless explicitly available>
+
+## Model Inventory
+
+| model_id | category | purpose | status | required_artifacts |
+| --- | --- | --- | --- | --- |
+| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required CSVs |
+| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required CSVs |
+| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required CSVs |
+| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required CSVs |
+| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required CSVs |
+| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
+
+## Model Record
+
+### <model-id>
+- category: smoke | analytical | patch test | benchmark | regression | negative/invalid-input
+- purpose: <what this model proves>
+- verified_requirements: [<requirement-id>]
+- analysis_type: <linear static | nonlinear static | modal | other>
+- element_type: <Abaqus element type and FESA feature element>
+- material: <material model and values>
+- boundary_conditions: <BC summary>
+- loads: <load summary>
+- expected_physical_quantities: displacement | reaction | element force | stress | strain | energy | residual
+- tolerance: <absolute/relative/norm policy or needs-user-decision>
+- source: <user | analytical | Abaqus Verification Guide | Abaqus Benchmarks Guide | NAFEMS | NASA/FEMCI | paper>
+- artifact_status: draft | needs-reference-artifacts | ready-for-implementation-planning | blocked
+
+## Abaqus Input Requirements
+- input_file: references/<feature-id>/<model-id>/model.inp
+- supported_keyword_subset: <keywords from docs/io-definitions/<feature-id>-io.md>
+- model_data: <nodes, elements, sets, material, section, coordinates, units>
+- history_data: <step, procedure, boundary conditions, loads, output requests>
+- output_requests: <requests needed to populate reference CSV files>
+- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision
+
+## Artifact Bundle Contract
+
+```text
+references/
+  <feature-id>/
+    <model-id>/
+      model.inp
+      metadata.json
+      displacements.csv
+      reactions.csv
+      element_forces.csv
+      stresses.csv
+      README.md
+```
+
+Required files:
+- `model.inp`: Abaqus input file for the reference model.
+- `metadata.json`: provenance and model contract metadata.
+- `displacements.csv`: nodal displacement reference results.
+- `reactions.csv`: nodal reaction force reference results.
+- `element_forces.csv`: element internal force reference results.
+- `stresses.csv`: stress reference results.
+- `README.md`: short description, generation notes, and limitations.
+
+Optional files:
+- `strains.csv`: strain reference results when required.
+- `energy_or_residual.csv`: energy, residual, or convergence reference results when required.
+- `notes.md`: manual review notes.
+
+## Metadata JSON Contract
+
+```json
+{
+  "feature_id": "<feature-id>",
+  "model_id": "<model-id>",
+  "artifact_status": "draft | needs-reference-artifacts | ready-for-implementation-planning | blocked",
+  "abaqus_version": "<version or needs-user-decision>",
+  "generation_owner": "<person/procedure>",
+  "generation_date": "<YYYY-MM-DD>",
+  "source_documents": ["docs/requirements/<feature-id>.md"],
+  "units": "<unit system>",
+  "coordinate_system": "global Cartesian unless otherwise documented",
+  "analysis_type": "<analysis type>",
+  "element_types": ["<Abaqus element type>"],
+  "material_values": {},
+  "boundary_condition_summary": "<summary>",
+  "load_summary": "<summary>",
+  "output_requests": ["U", "RF", "S", "<feature-specific quantities>"],
+  "csv_schema_version": "<version>",
+  "tolerance_policy": "<absolute/relative/norm policy>",
+  "limitations": ["<known limitation>"]
+}
+```
+
+## Reference CSV Requirements
+
+### displacements.csv
+- Required when nodal displacement is a verification quantity.
+- Must include step/frame identity, node id, displacement components, coordinate system, and units.
+
+### reactions.csv
+- Required when constrained DOF reactions or global equilibrium are verification quantities.
+- Must include step/frame identity, node id, reaction components, coordinate system, and units.
+
+### element_forces.csv
+- Required when element internal force is a verification quantity.
+- Must include step/frame identity, element id, output location, component, value, and units.
+
+### stresses.csv
+- Required when stress is a verification quantity.
+- Must include step/frame identity, element id, integration point or recovery location, component, value, coordinate system, and units.
+
+### Optional CSVs
+- `strains.csv`: required when strain is part of the acceptance criteria.
+- `energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
+
+## Coverage Matrix
+
+| requirement_id | model_id | compared_quantity | artifact_file | tolerance | verification_method | status |
+| --- | --- | --- | --- | --- | --- | --- |
+| <req-id> | <model-id> | displacement | displacements.csv | <policy> | reference-comparison | draft |
+| <req-id> | <model-id> | reaction | reactions.csv | <policy> | reference-comparison | draft |
+| <req-id> | <model-id> | element force | element_forces.csv | <policy> | reference-comparison | draft |
+| <req-id> | <model-id> | stress | stresses.csv | <policy> | reference-comparison | draft |
+
+## Artifact Acceptance Checklist
+- 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
+- `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
+- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 기록되어 있다.
+- 필수 CSV 파일이 존재하거나, 기능상 불필요한 파일은 명확한 reason과 함께 제외되어 있다.
+- output request가 필요한 CSV 물리량을 생성할 수 있도록 정의되어 있다.
+- reference CSV가 없으면 status는 `needs-reference-artifacts`다.
+- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
+
+## Open Issues and Downstream Handoff
+
+### I/O Definition Agent
+- <supported keyword, output request, CSV schema clarification>
+
+### Implementation Planning Agent
+- <tests that should fail before implementation, model order, acceptance criteria>
+
+### Reference Verification Agent
+- <CSV schema, ID matching, units, coordinate conventions, output locations, tolerance mapping>
+
+### Physics Evaluation Agent
+- <equilibrium, symmetry, displacement direction, stress location, rigid body mode, load path sanity checks>
+```
+
+## 품질 기준
+
+- Reference model의 목적과 검증 대상 requirement가 명확해야 한다.
+- `model.inp`는 Abaqus input file이며, 기능별 supported keyword subset을 따라야 한다.
+- model data와 history data를 구분해야 한다.
+- output request와 required CSV 사이의 연결이 명확해야 한다.
+- `references/<feature-id>/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
+- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 포함되어야 한다.
+- reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
+- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, tolerance, verification method로 추적되어야 한다.

docs/reference-verifications/README.md

@@ -0,0 +1,168 @@
+# Reference Verification Report 문서 작성 가이드
+
+이 디렉터리는 Reference Verification Agent가 작성하거나 제안하는 기능별 reference comparison report를 보관하는 위치다.
+
+Reference Verification Agent는 Build/Test Executor Agent 통과 후 generated solver result CSV와 stored Abaqus reference CSV artifacts를 tolerance 기준으로 비교한다. 이 agent는 comparison과 report만 수행하며, source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다.
+
+기본 문서명은 `docs/reference-verifications/<feature-id>-reference-verification.md` 형식을 사용한다.
+
+## Reference Verification Agent 역할
+
+수행한다:
+- `references/<feature-id>/<model-id>/` artifact bundle과 generated solver result CSV를 확인한다.
+- `metadata.json`, schema version, units, coordinate system, step/frame identity, node/element IDs, output location, tolerance source를 확인한다.
+- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv`를 기본 비교 대상으로 삼는다.
+- upstream 문서가 요구할 때만 `strains.csv`, `energy_or_residual.csv`를 추가 비교한다.
+- max absolute error, max relative error, RMS error, norm error, worst node/element/component, missing rows, extra rows, pass/fail을 보고한다.
+- 실패를 missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, unit-or-coordinate-mismatch, tolerance-failure, nonfinite-result, upstream-contract, environment로 분류한다.
+
+수행하지 않는다:
+- source code를 수정하지 않는다.
+- tests를 수정하지 않는다.
+- CMake files를 수정하지 않는다.
+- requirements, formulations, I/O contracts, reference model contracts를 수정하지 않는다.
+- reference artifacts 또는 tolerance policies를 수정하지 않는다.
+- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
+- reference CSV를 생성하지 않는다.
+- solver output CSV를 tolerance에 맞추기 위해 보정하지 않는다.
+- physics validation success 또는 release readiness를 승인하지 않는다.
+
+## 실행 순서
+
+Reference Verification Agent는 항상 다음 순서를 따른다.
+
+```text
+ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
+```
+
+`ARTIFACT CHECK`에서 다음 항목이 없으면 비교를 시작하지 않는다.
+
+- `metadata.json`
+- required reference CSV files
+- generated solver result CSV files
+- schema version
+- units
+- coordinate system
+- step/frame identity
+- node/element ID matching rule
+- output location
+- tolerance policy
+
+## 비교 대상
+
+기본 비교 대상:
+- `displacements.csv`: nodal displacement
+- `reactions.csv`: nodal reaction force
+- `element_forces.csv`: element internal force
+- `stresses.csv`: element stress
+
+선택 비교 대상:
+- `strains.csv`: strain이 acceptance criteria에 포함된 경우
+- `energy_or_residual.csv`: energy, residual, convergence quantity가 acceptance criteria에 포함된 경우
+
+## Failure Classification
+
+- `missing-reference-artifact`: required stored reference file 또는 provenance가 없다.
+- `missing-solver-output`: generated solver result CSV 또는 comparison command가 없다.
+- `schema-mismatch`: reference CSV와 solver CSV column/schema가 다르다.
+- `id-mismatch`: node id, element id, step/frame, integration point, component matching이 실패했다.
+- `unit-or-coordinate-mismatch`: units 또는 coordinate system이 비교 가능하지 않다.
+- `tolerance-failure`: schema와 matching은 유효하지만 error가 tolerance를 초과했다.
+- `nonfinite-result`: NaN 또는 infinite value가 발견됐다.
+- `upstream-contract`: tolerance, schema, units, output location, ID matching policy가 누락 또는 충돌한다.
+- `environment`: 로컬 실행 환경 문제로 비교가 불가능하다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Reference Verification Report
+
+## Metadata
+- feature_id: <feature-id>
+- source_build_test_report: docs/build-test-reports/<feature-id>-build-test.md
+- source_reference_models: docs/reference-models/<feature-id>-reference-models.md
+- source_io_definition: docs/io-definitions/<feature-id>-io.md
+- source_implementation_report: <path or N/A>
+- status: pass-for-physics-evaluation | needs-correction | needs-reference-artifacts | needs-solver-results | needs-upstream-decision | blocked
+- owner_agent: reference-verification-agent
+- date: <YYYY-MM-DD>
+
+## Artifact Inventory
+
+| item | path | status | notes |
+| --- | --- | --- | --- |
+| reference_bundle | references/<feature-id>/<model-id>/ | present | missing | <notes> |
+| metadata | references/<feature-id>/<model-id>/metadata.json | present | missing | <provenance summary> |
+| reference_displacements | references/<feature-id>/<model-id>/displacements.csv | present | missing | <notes> |
+| reference_reactions | references/<feature-id>/<model-id>/reactions.csv | present | missing | <notes> |
+| reference_element_forces | references/<feature-id>/<model-id>/element_forces.csv | present | missing | <notes> |
+| reference_stresses | references/<feature-id>/<model-id>/stresses.csv | present | missing | <notes> |
+| solver_outputs | <solver output directory> | present | missing | <notes> |
+
+## Comparison Contract
+- schema_version: <version>
+- id_matching: node_id | element_id | step/frame | integration_point | component
+- units: <unit system>
+- coordinate_system: <global/local convention>
+- output_location: nodal | element | integration_point | centroid | recovery_location
+- component_naming: <component naming policy>
+- tolerance_source: <requirement/reference model/I/O document>
+- tolerance_policy: absolute | relative | norm-based | combined
+- zero_reference_policy: <policy or N/A>
+
+## Quantity Results
+
+| quantity | model_id | artifact_file | compared_rows | missing_rows | extra_rows | max_abs_error | max_rel_error | rms_error | norm_error | worst_id | worst_component | result |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| displacement | <model-id> | displacements.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <node id> | <component> | pass | fail |
+| reaction | <model-id> | reactions.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <node id> | <component> | pass | fail |
+| element force | <model-id> | element_forces.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <element id> | <component> | pass | fail |
+| stress | <model-id> | stresses.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <element/ip id> | <component> | pass | fail |
+
+## Failure Classification
+- classification: missing-reference-artifact | missing-solver-output | schema-mismatch | id-mismatch | unit-or-coordinate-mismatch | tolerance-failure | nonfinite-result | upstream-contract | environment | N/A
+- primary_failure: <short summary>
+- evidence: <short relevant excerpt or computed metric>
+
+## Handoff Recommendation
+
+| target_agent | reason | required_input |
+| --- | --- | --- |
+| Correction Agent | <implementation-owned mismatch or nonfinite result> | <comparison metrics and failing quantity> |
+| Reference Model Agent | <missing or invalid reference artifact/provenance> | <artifact inventory> |
+| I/O Definition Agent | <schema, units, coordinate, output location mismatch> | <contract mismatch> |
+| Physics Evaluation Agent | <reference comparisons passed> | <quantity results and report> |
+| Coordinator Agent | <blocked or repeated ambiguity> | <classification and open issue> |
+
+## 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 solver outputs, missing reference artifacts, schema gaps, tolerance gaps, or repeated comparison failures>
+```
+
+## 상태 값
+
+- `pass-for-physics-evaluation`: required reference comparisons가 모두 통과했고 Physics Evaluation Agent로 넘길 수 있다.
+- `needs-correction`: implementation-owned solver result mismatch 또는 nonfinite result가 있다.
+- `needs-reference-artifacts`: required reference artifact 또는 provenance가 누락됐다.
+- `needs-solver-results`: generated solver result CSV 또는 comparison command가 없다.
+- `needs-upstream-decision`: schema, tolerance, units, coordinate system, output location, ID matching policy가 누락 또는 충돌한다.
+- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
+
+## 품질 기준
+
+- 모든 `must` requirement의 reference-comparison 항목은 model id, compared quantity, artifact file, tolerance에 trace되어야 한다.
+- reference artifact는 읽기 전용이다. `model.inp`, `metadata.json`, reference CSV를 수정하지 않는다.
+- solver output CSV는 비교 입력일 뿐이며 tolerance에 맞추기 위해 후처리 보정하지 않는다.
+- stress/strain은 element id, integration point 또는 recovery location, component naming이 일치할 때만 비교한다.
+- nodal displacement/reaction은 node id, DOF/component, coordinate system, unit이 일치할 때만 비교한다.
+- missing rows와 extra rows를 숨기지 않고 보고한다.
+- NaN 또는 infinite value는 `nonfinite-result`로 분류한다.
+- pass는 reference tolerance 통과만 의미한다.
+- physics validation과 release readiness는 각각 Physics Evaluation Agent와 Release Agent가 판정한다.

docs/releases/README.md

@@ -0,0 +1,171 @@
+# 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 자동화는 포함하지 않는다.