docs: align consolidated solver workflow

2026-08-15 03:14:34 +09:00
parent a8efe2b738
commit 925c4851c9
71 changed files with 687 additions and 937 deletions
@@ -1,415 +1,175 @@
-# 구조해석 솔버 개발 Agent 구성안
+# FESA Solver Agent Design

-## 목적
-이 문서는 Abaqus, Nastran과 같은 유한요소법 기반 구조해석 솔버를 개발하기 위한 AI Agent 운영 구성을 정의한다.
+## 목적과 범위

-이번 구성안은 ALL-FEM 논문의 구조를 확장하거나 재사용하는 계획이 아니다. 논문은 Agent 설계를 위한 참고 자료로만 사용하며, 본 프로젝트는 C++/MSVC 기반 독립 솔버 개발 워크플로우를 따른다.
+이 문서는 FESA 기능 개발을 조정하는 agent 계층, 8단계 workflow, gate와 산출물 계약을
+정의한다. `coordinator-agent`가 유일한 main agent이며, 나머지 10개 profile은 Coordinator가
+호출하는 sub-agent다. 모든 기능별 agent 산출물은 `docs/<feature-id>/`에 모은다.

-## 설계 원칙
- 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
- 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
- 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. 기능이 선언한 기존 `.inp`와 실제
-  비교에 필요한 Abaqus CSV만 read-only 검증 기준으로 사용한다. Canonical naming,
-  README, metadata, version 또는 provenance는 기본 readiness 조건이 아니다.
- FESA는 Abaqus와 독립적인 solver다. Agent는 Abaqus 내부 formulation, integration,
-  stabilization 또는 recovery equivalence를 요구하거나 추론하지 않는다.
- 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
- Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.
+이 workflow는 개발 운영 계약이다. Solver C++ 아키텍처, CMake/CTest target, Harness
+executor와 hook, Abaqus reference artifact 또는 승인된 FEM 기능 의미를 바꾸지 않는다.

-## Harness Step 실행 계약
+## Agent 계층

-계획과 구현 Agent는 작업 전 `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.
-Implementation Planning Agent는 multi-Step 초안을 사용자에게 승인받은 뒤 planning files만
-materialize하며 Step을 선택하거나 실행하지 않는다. Executor는 별도의 명시적 사용자 요청으로
-`scripts/execute.py`를 실행할 때 branch, pending Step 선택, retry, timestamps, commits, Step
-advancement와 phase status를 소유한다.
+### Coordinator Agent: main-agent orchestration

-Implementation Agent는 approved plan, materialized phase files, Executor-selected current
-`stepN.md`만 사용해 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`를 완료하고
-다음 Step을 시작하지 않는다. Agent가 쓸 수 있는 Harness metadata는 current Step의 `status`와
-`summary`, `error_message`, `blocked_reason` payload뿐이다. `.codex/hooks.json`이 PreToolUse
-interception과 Stop whole-project validation을 자동 실행하므로 hook entry point를 수동 실행해
-대체하지 않는다. 세부 schema와 recovery 절차는 `docs/HARNESS_WORKFLOW.md`를 따른다.
+Coordinator Agent는 기능 요청을 접수하고 다음 실행 loop를 소유한다.

-## 전체 Agent 구성
+```text
+INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
+       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT
+```

-### Coordinator Agent
-전체 개발 흐름을 관리하는 상위 조정 Agent이다.
+- `docs/<feature-id>/coordination.md`의 8단계 worklist와 현재 workflow state를 관리한다.
+- 한 번에 다음 유효 단계의 owner만 bounded task로 dispatch한다.
+- 반환된 산출물 경로, status, evidence와 blocker를 검토한 뒤에만 gate를 전환한다.
+- Specialist 판단이나 C++ 구현을 대신하지 않으며, evidence 없이 gate를 통과시키지 않는다.
+- 동일한 normalized failure classification이 두 번 발생하면 자동 재작업을 멈추고
+  `needs-user-decision` 또는 `blocked`로 전환한다.
+- Release evidence가 `ready-for-release`일 때 최종 closure를 기록한다.

-책임:
- 기능 개발 요청을 단계별 작업으로 분해한다.
- 각 Agent의 산출물을 연결하고 누락된 결정을 추적한다.
- 요구조건, 정식화, 테스트, 구현, 검증, 배포 단계의 진행 상태를 관리한다.
- 실패 시 어떤 Agent로 되돌릴지 결정한다.
+Worklist item은 `pending | in-progress | passed | needs-rework | blocked`만 사용한다.
+Sub-agent는 전달받은 단계와 산출물만 처리하며 peer를 호출하거나 다음 단계로 진행하지
+않는다. 완료 시 output paths, status, evidence summary와 blockers를 Coordinator에 반환한다.

-주요 산출물:
- 기능별 개발 계획
- 단계별 승인 상태
- 실패 원인과 재작업 지시
+## 10개 sub-agent 역할

 ### Requirement Agent
-솔버 기능 요구조건을 정의하는 Agent이다.

-책임:
- 해석 기능의 범위, 입력, 출력, 제약조건을 정의한다.
- 대상 요소, 재료 모델, 경계조건, 하중 조건, 해석 타입을 명확히 한다.
- 검증해야 할 물리량과 tolerance 기준을 정한다.
-
-주요 산출물:
- 기능 요구조건 문서
- acceptance criteria
- 검증 물리량 목록
-
-예시 검증 물리량:
- 절점 변위
- 반력
- 요소 내력
- 응력
- 변형률
- 에너지 또는 잔차 기준
+검증 가능한 범위, 제외 범위, `shall` 요구조건, acceptance criteria, verification quantity와
+tolerance baseline을 `requirements.md`에 정의한다.

 ### Research Agent
-책, 논문, 매뉴얼, 공개 benchmark를 조사하는 Agent이다.

-책임:
- 유한요소 정식화에 필요한 이론 자료를 수집한다.
- 요소별 benchmark와 patch test 사례를 찾는다.
- Abaqus/Nastran 결과와 비교할 수 있는 공개 예제 또는 문헌 해를 조사한다.
- 자료의 신뢰도와 적용 범위를 평가한다.
-
-주요 산출물:
- 연구자료 요약
- 공식, 가정, 한계 정리
- benchmark 후보 목록
+이론, solver manual, benchmark와 source reliability를 조사하고 확인된 사실과 추론 및
+applicability limit를 `research.md`에 분리해 기록한다.

 ### Formulation Agent
-코드 구현을 위한 유한요소 정식화를 작성하는 Agent이다.

-책임:
- 약형, 형상함수, B matrix, constitutive matrix, 수치적분, 요소 강성 행렬을 정의한다.
- 자유도 배치, 좌표계, 단위계, 부호 규약을 명확히 한다.
- 선형/비선형, 정적/동적, small/large deformation 여부를 구분한다.
- 구현 가능한 알고리즘 형태로 정식화를 정리한다.
-
-주요 산출물:
- 요소별 정식화 문서
- 알고리즘 의사코드
- 수치적분 규칙
- edge case와 singular case 목록
+Strong/weak form, kinematics, constitutive contract, shape functions, element equation, numerical
+integration과 output recovery를 구현 가능한 수치 계약으로 `formulation.md`에 작성한다.

 ### Numerical Review Agent
-정식화와 수치 알고리즘을 독립 검토하는 Agent이다.

-책임:
- 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
- rigid body mode, patch test, symmetry, positive definiteness 등 기본 수치 조건을 확인한다.
- locking, hourglass mode, ill-conditioning 같은 위험을 식별한다.
- 구현 전 정식화 오류를 줄인다.
-
-주요 산출물:
- 정식화 리뷰 결과
- 수치 위험 목록
- 추가 테스트 요구사항
+독립적인 formulation 검토와 reference readiness를 하나의 merged gate로 소유한다. 차원,
+부호, DOF 순서, 좌표 변환, Jacobian, 적분, 대칭성, rigid-body mode, locking과 검증 위험을
+`numerical-review.md`에 기록한다. 동시에 exact reference input/CSV, blocking/warning quantity,
+source identity/component, row precheck와 승인 tolerance를 `reference-model.md`에 정의한다.
+두 문서가 모두 준비되어야 I/O 단계로 handoff할 수 있다.

 ### I/O Definition Agent
-솔버 입력과 출력 데이터 구조를 정의하는 Agent이다.

-책임:
- mesh, node, element, material, section, boundary condition, load, step 입력 형식을 정의한다.
- authoritative HDF5 result schema와 reference CSV comparison row schema를 정의한다.
- Abaqus input file과 내부 입력 모델 사이의 대응 관계를 정리한다.
- 결과 비교를 위해 FESA HDF5 dataset과 Abaqus reference CSV row의 ID/컴포넌트 규약을 맞춘다.
-
-주요 산출물:
- 입력 데이터 schema
- 출력 데이터 schema
- HDF5 result schema
- 결과 비교용 deterministic CSV view schema
- 단위와 좌표계 규약
-
-### Reference Model Agent
-TDD와 검증에 사용할 기존 reference case를 inventory하는 Agent이다.
-
-책임:
- 기능이 요구할 때만 테스트 모델 목적을 구분하고, 기본적으로 기존 case를 사용한다.
- 기존 reference case의 목적, exact input/required CSV path, blocking/warning quantity와
-  tolerance를 inventory한다.
- FESA HDF5 quantity와 source ID/component matching을 명시한다.
- 테스트 모델이 요구조건을 실제로 검증하는지 확인한다.
-
-중요 제약:
- Agent는 Abaqus를 직접 실행하지 않는다.
- Abaqus 해석 결과 CSV는 사람이 생성하거나 별도 승인된 절차로 생성해 `reference/<model-id>/`에 저장한다.
- Agent는 저장된 reference artifact만 사용해 비교한다.
-
-최소 reference case 구조:
-```text
-reference/
-  <case-dir>/
-    <declared-input>.inp
-    <declared-required-quantity>.csv
-```
-
-Directory와 filename은 제공된 값을 그대로 사용한다. Reference Model Agent는 canonical
-이름, README, metadata, provenance 또는 비교하지 않는 quantity CSV를 요구하지 않는다.
+승인된 Abaqus `.inp` subset, semantic model mapping, validation diagnostic, authoritative
+`results.h5` schema와 reference CSV row schema를 `io.md`에 정의한다. Numerical/reference
+gate가 확정한 logical quantity와 source identity를 최종 HDF5 dataset projection 및 CSV
+column mapping으로 연결하는 책임은 이 agent에 있다.

 ### Implementation Planning Agent
-코드 구현 전에 작업 단위와 테스트 순서를 설계하는 Agent이다.

-책임:
- 요구조건과 정식화를 C++ 구현 작업으로 분해한다.
- 먼저 작성할 단위 테스트, 통합 테스트, 레퍼런스 비교 테스트를 정의한다.
- 기존 architecture와 ownership boundary에 맞춰 변경 파일을 제한한다.
- 구현 Agent가 따라야 할 acceptance criteria를 제공한다.
-
-주요 산출물:
- 구현 계획
- 테스트 우선순위
- 변경 파일 후보
- acceptance checklist
- 사용자 승인 전 multi-Step Harness 초안
- 승인 후 `phases/index.json`, `phases/<task-name>/index.json`, 자기완결적 `stepN.md`
-
-필수 절차:
- 구현 계획 요청에서 project-local `$harness` skill을 사용한다.
- `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽고 multi-Step 초안만 사용자에게
-  제시한다.
- 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD
-  RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다.
- Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다.
- 승인 후에는 planning files만 materialize하고 Step 선택/실행은 하지 않는다. Harness executor
-  실행은 별도 사용자 요청이 있을 때만 수행한다.
+승인된 upstream bundle을 자기완결적 TDD Step으로 분해해 `implementation-plan.md`를 만든다.
+계획 요청에서는 project-local `harness`를 사용하고 사용자에게 multi-Step 초안을 먼저
+제시한다. 승인 후에만 phase index와 `stepN.md`를 materialize하며 executor는 별도 명시
+요청이 있을 때만 실행한다.

 ### Implementation Agent
-C++ 코드를 구현하는 Agent이다.

-책임:
- `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, materialized phase files와
-  Executor-selected current `stepN.md`를 읽고 현재 Step만 수행한다.
- 테스트를 먼저 작성하고 실패를 확인한다.
- 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
- C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
- 불필요한 일반화나 speculative abstraction을 피한다.
- current Step의 `status`와 `summary`, `error_message`, `blocked_reason`만 기록한다.
-  branch, retry, timestamp, commit, advancement는 Executor에 맡긴다.
- `.codex/hooks.json`으로 자동 등록된 PreToolUse와 Stop을 사용하며 hook script를 수동
-  검증 대체물로 실행하지 않는다.
-
-주요 산출물:
- C++ source/header 변경
- 테스트 코드
- CMake/CTest 변경
-
-### Build/Test Executor Agent
-빌드와 테스트를 실행하는 Agent이다.
-
-책임:
- `.harness/config.json` 또는 자동 감지 결과에 맞는 MSVC build/test 명령을 실행한다.
- MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
- 실패 로그를 요약하고 Correction Agent에 전달한다.
-
-기본 CMake 검증 명령:
-```powershell
-cmake -S . -B .harness/build -A x64
-cmake --build .harness/build --config Debug
-ctest --test-dir .harness/build -C Debug --show-only=json-v1
-ctest --test-dir .harness/build -C Debug --output-on-failure
-```
-
-Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 선언된 명령을 따른다.
-
-검증 대상:
- CMake configure
- MSVC Debug build
- CTest
- Harness self-test
+승인된 Step 단위로 `RED -> observed failure -> minimal GREEN -> focused VERIFY`를 수행하고,
+full MSVC x64 Debug build/CTest와 reference comparison까지 하나의 Implementation gate에서
+완료한다. `implementation-report.md`, `build-test.md`, `reference-comparison.md`를 각각 남기며
+최종 성공 status는 `pass-for-physics-evaluation`이다.

 ### Correction Agent
-빌드, 테스트, 런타임 실패를 수정하는 Agent이다.

-책임:
- 실패 로그를 원인별로 분류한다.
- 컴파일 오류, 링크 오류, 테스트 실패, 결과 비교 실패를 구분한다.
- 최소 수정으로 실패를 해결한다.
- 같은 실패가 반복되면 Coordinator Agent에 차단 상태를 보고한다.
-
-주요 산출물:
- 수정 패치
- 실패 원인 요약
- 재검증 요청
-
-### Reference Verification Agent
-구현 솔버 결과와 저장된 레퍼런스 결과를 비교하는 Agent이다.
-
-책임:
- 구현 솔버 `results.h5`의 rows와 `reference/<model-id>/`의 Abaqus reference CSV rows를 비교하고, FESA debug CSV views는 row identity 검토와 report evidence로만 사용한다.
- 절점 변위, 반력, 요소 내력, 응력의 tolerance 만족 여부를 평가한다.
- absolute tolerance, relative tolerance, norm-based tolerance를 구분해 적용한다.
- 결과 차이가 tolerance 밖이면 원인 후보를 분류한다.
-
-주요 산출물:
- reference comparison report
- 실패한 물리량과 위치
- 최대 오차, 평균 오차, norm 오차
+정규 단계가 아닌 on-demand rework sub-agent다. 같은 실패가 반복되거나 원인이 불명확할
+때 Coordinator가 호출한다. Upstream 계약을 바꾸지 않고 최소 수정과 재검증을 수행해
+`corrections.md`에 누적하고 Implementation Agent 재실행 요청을 Coordinator에 반환한다.

 ### Physics Evaluation Agent
-수치 결과가 물리적으로 타당한지 검토하는 Agent이다.

-책임:
- 레퍼런스와 수치적으로 비슷해도 물리적으로 이상한 결과가 있는지 확인한다.
- 변위 방향, 반력 평형, 응력 집중, 대칭 조건, rigid body mode를 검토한다.
- 테스트 모델이 기능을 충분히 검증하지 못하면 추가 모델을 요구한다.
-
-주요 산출물:
- 물리 검토 결과
- 추가 검증 모델 요구사항
- release 가능 여부 의견
+Reference comparison 이후 equilibrium, reaction consistency, displacement direction, symmetry,
+element force balance, stress/strain sanity, rigid-body mode와 model coverage를 검토해
+`physics-evaluation.md`에 기록한다.

 ### Release Agent
-기능 배포 준비를 담당하는 Agent이다.

-책임:
- 요구조건, 테스트, 레퍼런스 비교, 물리 검토가 모두 통과했는지 확인한다.
- 기능 문서와 release note를 정리한다.
- 알려진 제한사항과 tolerance 기준을 기록한다.
+Requirements부터 physics까지 gate evidence와 acceptance traceability를 audit하고 known
+limitations, release notes draft와 release verdict를 `release.md`에 기록한다. 내부 readiness
+판정은 publish, deploy, package, tag 또는 external release 권한이 아니다.

-주요 산출물:
- release checklist
- 기능 문서
- known limitations
+## 8단계 개발 프로세스

-## 개발 프로세스 매핑
+| 단계 | 담당 sub-agent | 필수 skill | `docs/<feature-id>/` 산출물 | 통과 조건 |
+| --- | --- | --- | --- | --- |
+| 1. 요구조건 | `requirement-agent` | `fesa-requirements-baseline` | `requirements.md` | 승인 범위, acceptance criteria, 검증량과 tolerance가 명확함 |
+| 2. 연구 | `research-agent` | `fesa-research-evidence`, 필요 시 `fem-theory-query` | `research.md` | 이론과 검증 evidence 및 적용 한계가 충분함 |
+| 3. 정식화 | `formulation-agent` | `fesa-formulation-spec` | `formulation.md` | 구현 가능한 수치 계약이 완성됨 |
+| 4. 수치 검토 + reference model 계약 | `numerical-review-agent` | `fesa-numerical-review` | `numerical-review.md`, `reference-model.md` | 두 문서가 함께 `pass-for-io-definition`임 |
+| 5. I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `io.md` | Logical reference identity가 최종 HDF5 projection과 연결됨 |
+| 6. 구현 계획 + C++ 구현 + build/test + reference comparison | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd`, 계획 시 project-local `harness` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md` | TDD, full MSVC/CTest와 blocking reference comparison이 모두 통과함 |
+| 7. 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `physics-evaluation.md` | 물리 검토가 `pass-for-release-agent`임 |
+| 8. 배포 준비 | `release-agent` | `fesa-release-readiness` | `release.md` | `ready-for-release`이며 Coordinator가 closure를 기록함 |

-| 개발 과정 | 담당 Agent | 필수 산출물 |
-| --- | --- | --- |
-| 1. 솔버 기능 요구조건 정의 | Requirement Agent | 요구조건, acceptance criteria |
-| 2. 연구자료 조사 | Research Agent | 자료 요약, benchmark 후보 |
-| 3. 유한요소 정식화 | Formulation Agent, Numerical Review Agent | 정식화 문서, 리뷰 결과 |
-| 4. 입출력 데이터 정의 | I/O Definition Agent | 입력/출력 schema |
-| 5. Reference case 준비 | Reference Model Agent, Implementation Planning Agent | 기존 input/required CSV inventory, 비교 mapping, tolerance |
-| 6. 코드 구현 | Implementation Agent | C++ 코드, 테스트 |
-| 7. 레퍼런스 결과 비교 검증 | Reference Verification Agent, Physics Evaluation Agent | 비교 리포트, 물리 검토 |
-| 8. tolerance 만족 시 완료 | Coordinator Agent | 기능 완료 승인 |
-| 9. 기능 배포 | Release Agent | release checklist, 문서 |
-
-## 표준 작업 흐름
+## 8단계 workflow

 ```mermaid
 flowchart TD
-  A["기능 요청"] --> B["Requirement Agent"]
-  B --> C["Research Agent"]
-  C --> D["Formulation Agent"]
-  D --> E["Numerical Review Agent"]
-  E --> F["I/O Definition Agent"]
-  F --> G["Reference Model Agent"]
-  G --> H["Implementation Planning Agent"]
-  H --> I["Implementation Agent"]
-  I --> J["Build/Test Executor Agent"]
-  J --> K{"빌드/테스트 통과?"}
-  K -- "아니오" --> L["Correction Agent"]
-  L --> I
-  K -- "예" --> M["Reference Verification Agent"]
-  M --> N{"tolerance 만족?"}
-  N -- "아니오" --> L
-  N -- "예" --> P["Physics Evaluation Agent"]
-  P --> Q{"물리 검토 통과?"}
-  Q -- "아니오" --> L
-  Q -- "예" --> R["Release Agent"]
+  C["Coordinator: intake 및 worklist"] --> RQ["1. Requirement Agent"]
+  RQ --> RS["2. Research Agent"]
+  RS --> FM["3. Formulation Agent"]
+  FM --> NR["4. Numerical Review Agent<br/>numerical + reference gate"]
+  NR --> IO["5. I/O Definition Agent<br/>final HDF5 projection"]
+  IO --> IP["6. Implementation Planning Agent"]
+  IP --> IM["6. Implementation Agent<br/>TDD + MSVC/CTest + reference comparison"]
+  IM --> OK{"Implementation gate pass?"}
+  OK -- "yes" --> PH["7. Physics Evaluation Agent"]
+  OK -- "repeated or unclear failure" --> CR["Correction Agent<br/>on-demand rework"]
+  CR --> IM
+  PH --> RL["8. Release Agent"]
+  RL --> CL["Coordinator: closure"]
 ```

-## 검증 Gate
+Compile, link, ordinary test와 명확한 implementation-owned mismatch는 Implementation Agent가
+먼저 수정한다. 반복되거나 불명확한 실패만 Correction loop로 보낸다. Upstream contract
+gap은 Coordinator가 해당 owner 단계로 되돌린다.

-### Gate 1: 요구조건 승인
-통과 조건:
- 대상 기능과 제외 범위가 명확하다.
- 입력, 출력, tolerance, 검증 물리량이 정의되어 있다.
- 레퍼런스 비교 방식이 정해져 있다.
+## Gate 계약

-### Gate 2: 정식화 승인
-통과 조건:
- 요소 정식화와 수치적분 규칙이 문서화되어 있다.
- 좌표계, 자유도, 부호 규약이 명확하다.
- Numerical Review Agent가 주요 수치 위험을 검토했다.
+1. Requirements gate: `requirements.md`가 범위, acceptance criteria, 검증량과 tolerance를
+   고정한다.
+2. Research gate: `research.md`가 필요한 이론, benchmark와 applicability evidence를 제공한다.
+3. Formulation gate: `formulation.md`가 구현 가능한 수치 계약을 제공한다.
+4. Numerical/reference merged gate: `numerical-review.md`와 `reference-model.md`가 함께 통과한다.
+5. I/O gate: `io.md`가 source identity와 logical quantity를 authoritative `results.h5` dataset,
+   units, coordinates, component와 CSV column에 최종 투영한다.
+6. Implementation gate: 승인 계획, RED/GREEN/VERIFY evidence, full MSVC x64 Debug build/CTest,
+   deterministic row precheck와 blocking/warning reference comparison이 모두 통과한다.
+7. Physics gate: `physics-evaluation.md`가 `pass-for-release-agent`다.
+8. Release gate: `release.md`가 `ready-for-release`이고 Coordinator가 closure를 기록한다.

-### Gate 3: 테스트 준비 승인
-통과 조건:
- 구현 전 실패해야 하는 테스트가 정의되어 있다.
- 기능이 요구하는 기존 input/CSV pair와 blocking/warning quantity가 명확하다.
- 필요한 source ID/component matching과 tolerance가 정의되어 있다.
+Reference comparison은 source identity와 component로 행을 결정적으로 대응시키며 missing,
+extra, duplicate 또는 nonfinite required row를 tolerance 전에 거부한다. CSV는 외부 reference이고
+FESA의 authoritative output은 `results.h5`다.

-### Gate 4: 구현 검증
-통과 조건:
- CMake/MSVC/CTest validation이 통과한다.
- 단위 테스트와 통합 테스트가 통과한다.
- 관련 C++ test file이 있고 같은 구현 Step 안에 RED 실패와 후속 GREEN 성공 증거가 있다.
- Stop의 전체 MSVC build/test 검증이 통과한다.
+## 요구사항 단위 산출물 구조

-### Gate 5: 레퍼런스 검증
-통과 조건:
- 기능이 blocking으로 선언한 Abaqus CSV quantity와 구현 solver HDF5 quantity가
-  tolerance 안에 있다.
- Warning-only quantity는 결과와 경고가 리포트에 남고 pass/fail을 바꾸지 않는다.
- Required source row/component의 누락, 추가, 중복 또는 nonfinite 값이 없다.
+```text
+docs/<feature-id>/
+├── coordination.md
+├── requirements.md
+├── research.md
+├── formulation.md
+├── numerical-review.md
+├── reference-model.md
+├── io.md
+├── implementation-plan.md
+├── implementation-report.md
+├── build-test.md
+├── reference-comparison.md
+├── corrections.md
+├── physics-evaluation.md
+└── release.md
+```

-### Gate 6: 배포 승인
-통과 조건:
- 요구조건의 acceptance criteria가 모두 만족된다.
- 문서와 release note가 준비되어 있다.
- 남은 제한사항이 명확히 기록되어 있다.
-
-## FESA HDF5 / Abaqus Reference CSV 비교 기준
-
-권장 비교 방식:
- authoritative 비교는 FESA `results.h5` rows와 Abaqus reference CSV rows 기준으로 수행한다.
- FESA HDF5에서 추출한 deterministic CSV view는 debugging/review 보조 artifact로만 사용한다.
- scalar 값: absolute tolerance와 relative tolerance를 함께 적용한다.
- vector 값: component-wise 비교와 norm 비교를 함께 기록한다.
- stress tensor: component-wise 비교를 기본으로 하고, 필요한 경우 principal stress 또는 von Mises stress를 추가 비교한다.
- 반력: 전체 하중 평형과 개별 구속 자유도 반력을 모두 확인한다.
-
-권장 리포트 항목:
- model name
- compared quantity
- number of compared rows
- maximum absolute error
- maximum relative error
- RMS error
- worst node or element id
- pass/fail
-
-## 반복 실패 처리
-
-반복 실패가 발생하면 Correction Agent가 무한 수정 루프를 계속하지 않는다. 다음 중 하나로 분류해 Coordinator Agent에 보고한다.
-
- 요구조건 불명확
- 정식화 오류 가능성
- reference artifact 오류 가능성
- I/O schema 불일치
- 구현 결함
- tolerance 기준 부적절
- 테스트 모델이 기능을 과도하게 또는 불충분하게 검증함
-
-Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Definition, Reference Model, Implementation Agent 중 적절한 단계로 되돌린다.
-
-## 초기 적용 우선순위
-
-1. 선형 정적 해석의 최소 골격
-2. Isoparametric 3D Euler beam element
-3. 1D truss 또는 bar element
-4. 2D plane stress/plane strain element
-5. 3D solid element
-6. material model 확장
-7. nonlinear 또는 dynamic analysis 확장
-
-각 단계는 요구조건, 정식화, 테스트모델, 구현, 레퍼런스 비교, 배포 Gate를 독립적으로 통과해야 한다.
-
-## 운영 메모
-
- Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
- 사람이 제공한 Abaqus reference artifact는 현재 path/name 그대로 read-only로 사용한다.
-  별도 provenance, README 또는 metadata가 없다는 이유로 gate를 차단하지 않는다.
- reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
- 기능 구현 완료 판정은 build/test와 기능별 blocking reference validation 통과를 기준으로
-  한다. Physics evaluation과 release readiness는 별도 후속 배포 gate다.
+산출물이 필요하지 않았거나 기존 workflow에 없었던 경우 placeholder를 만들지 않는다.
+`corrections.md`는 실제 on-demand correction이 발생했을 때만 생성한다. Reference input/CSV는
+현재 path와 name 그대로 read-only로 사용하고, 문서 정리를 위해 rename 또는 보정하지 않는다.