FESADev/docs/SOLVER_AGENT_DESIGN.md

FESA Solver Agent Design

목적과 범위

이 문서는 FESA 기능 개발을 조정하는 agent 계층, 8단계 workflow, gate와 산출물 계약을 정의한다. coordinator-agent가 유일한 main agent이며, 나머지 10개 profile은 Coordinator가 호출하는 sub-agent다. 모든 기능별 agent 산출물은 docs/<feature-id>/에 모은다.

이 workflow는 개발 운영 계약이다. Solver C++ 아키텍처, CMake/CTest target, Harness executor와 hook, Abaqus reference artifact 또는 승인된 FEM 기능 의미를 바꾸지 않는다.

Agent 계층

Coordinator Agent: main-agent orchestration

Coordinator Agent는 기능 요청을 접수하고 다음 실행 loop를 소유한다.

INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT

• 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를 기록한다.

Worklist item은 pending | in-progress | passed | needs-rework | blocked만 사용한다. Sub-agent는 전달받은 단계와 산출물만 처리하며 peer를 호출하거나 다음 단계로 진행하지 않는다. 완료 시 output paths, status, evidence summary와 blockers를 Coordinator에 반환한다.

10개 sub-agent 역할

Requirement Agent

검증 가능한 범위, 제외 범위, shall 요구조건, acceptance criteria, verification quantity와 tolerance baseline을 requirements.md에 정의한다.

Research Agent

이론, solver manual, benchmark와 source reliability를 조사하고 확인된 사실과 추론 및 applicability limit를 research.md에 분리해 기록한다.

Formulation Agent

Strong/weak form, kinematics, constitutive contract, shape functions, element equation, numerical integration과 output recovery를 구현 가능한 수치 계약으로 formulation.md에 작성한다.

Numerical Review Agent

독립적인 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

승인된 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

승인된 upstream bundle을 자기완결적 TDD Step으로 분해해 implementation-plan.md를 만든다. 계획 요청에서는 project-local harness를 사용하고 사용자에게 multi-Step 초안을 먼저 제시한다. 승인 후에만 phase index와 stepN.md를 materialize하며 executor는 별도 명시 요청이 있을 때만 실행한다.

Implementation Agent

승인된 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

정규 단계가 아닌 on-demand rework sub-agent다. 같은 실패가 반복되거나 원인이 불명확할 때 Coordinator가 호출한다. Upstream 계약을 바꾸지 않고 최소 수정과 재검증을 수행해 corrections.md에 누적하고 Implementation Agent 재실행 요청을 Coordinator에 반환한다.

Physics Evaluation Agent

Reference comparison 이후 equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid-body mode와 model coverage를 검토해 physics-evaluation.md에 기록한다.

Release Agent

Requirements부터 physics까지 gate evidence와 acceptance traceability를 audit하고 known limitations, release notes draft와 release verdict를 release.md에 기록한다. 내부 readiness 판정은 publish, deploy, package, tag 또는 external release 권한이 아니다.

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를 기록함

8단계 workflow

flowchart TD
  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"]

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

Gate 계약

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를 기록한다.

Reference comparison은 source identity와 component로 행을 결정적으로 대응시키며 missing, extra, duplicate 또는 nonfinite required row를 tolerance 전에 거부한다. CSV는 외부 reference이고 FESA의 authoritative output은 results.h5다. 공통 tolerance 값, family 구성, row/RMS 판정, report evidence와 변경 관리는 docs/TOLERANCE.md를 따른다.

요구사항 단위 산출물 구조

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

산출물이 필요하지 않았거나 기존 workflow에 없었던 경우 placeholder를 만들지 않는다. corrections.md는 실제 on-demand correction이 발생했을 때만 생성한다. Reference input/CSV는 현재 path와 name 그대로 read-only로 사용하고, 문서 정리를 위해 rename 또는 보정하지 않는다.