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를 소유한다.

```text
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

```mermaid
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`를 따른다.

## 요구사항 단위 산출물 구조

```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
```

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