FESADev/docs/SOLVER_AGENT_DESIGN.md

# Structural FEM Solver Agent Design

## 목적

메인 assistant가 작업 분해, 필요한 specialist 선택, 구현 조정과 완료 확인을 담당한다.
작은 문서·구현·일상 결함은 직접 처리한다. Specialist는 전문 판단이나 독립 검토가
필요한 bounded task에 사용하며 고정 lifecycle을 순회하기 위해 호출하지 않는다.

현재 운영 결정은 [ADR-028](ADR.md#adr-028), Feature 폴더와 산출물 관리는
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 필요한 계약과 검증은
유지하면서 문맥 재독, 형식적 인계와 같은 결과의 반복 검토를 줄인다.

## 권한과 판단 기준

충돌하는 정보는 다음 우선순위로 판단한다.

1. 현재 사용자 요청의 범위·권한과 승인된 Feature contract·critical decision
2. 지배 방정식, 수학적 일관성, 적용 표준과 검증된 1차 문헌
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 검증 사례
4. 프로젝트 지침, architecture, ADR, tolerance와 기존 승인 계약
5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현

Abaqus는 외부 reference convention이다. 지원 subset의 공개 입력 의미와 승인된 비교량을
참고하되 비공개 알고리즘·내부 상태·결과 생성 절차를 추정하거나 내부 동등성을 주장하지
않는다. 수치 결과의 exact equality는 허용되지만 내부 동등성의 evidence가 아니다.
의미상 무해하다고 계약된 항목만 명시적 warning/no-op으로 처리하고 그 밖의 미지원
semantics는 fail-closed로 진단한다.

## 메인의 작업 조정

메인은 관련 계약과 현재 evidence를 확인하여 작업·수정 파일·검증 기준을 정한다.
새 Feature에 지속할 계약이나 근거가 필요하면 `docs/<feature-id>/`를 초기화하고
`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 작은 수정에는 새 Feature 폴더나
빈 보고서를 만들지 않는다. 현재 checklist는 PRD 한 곳에 둔다.

메인은 계획·구현·일반 실패 수정을 직접 수행하거나 필요한 구현 묶음을 위임할 수 있다.
Specialist는 할당된 판단과 파일만 소유하며 다른 계약을 수정하거나 peer를 재위임하지
않는다. 메인은 결과를 확인하되 독립 검토가 필요한 판단을 작성자의 자기 승인으로 대체하지
않는다. 누락된 evidence는 통과가 아니다.

## Specialist 선택

현재 profile은 [`.codex/agents`](../.codex/agents)에 있다.

| Specialist | 호출할 때 | 기본 추론 강도 |
| --- | --- | --- |
| `requirement-agent` | 범위·acceptance가 복잡하거나 상충하여 별도 계약 정리가 필요 | `medium` |
| `research-agent` | 사용할 이론·benchmark·reference 근거가 부족 | `medium` |
| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화가 필요 | `high` |
| `numerical-review-agent` | 새 정식화·주요 수치 변경·원인 불명의 수치 불일치를 독립 검토 | `high` |
| `io-definition-agent` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경 | `medium` |
| `implementation-agent` | 메인이 직접 수행하기보다 위임할 이점이 있는 구현 묶음 | `medium` |
| `physics-evaluation-agent` | 새 해석 기능이나 결과의 평형·물리적 타당성·coverage 평가가 필요 | `high` |

수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review를 수행한다.
역할의 조건부 호출은 해당 analytical/invariant 검증이나 계약상 필수 물리·reference
검증을 생략할 근거가 아니다. Release-readiness 감사는 사용자 명시 요청 시에만
`fem-release-readiness`로 수행하며 전용 release profile이나 필수 종료 stage를 두지 않는다.

모델과 역할별 강도는 현재 profile을 따른다. 난해한 정식화·수렴 문제에만 필요한 범위에서
강도를 높인다. Profile 변경만으로 이미 실행 중인 session의 설정이 갱신되었다고 가정하지
않는다. 불필요한 진행 확인·보고서 재작성·같은 결과의 재검토를 위해 agent를 호출하지 않는다.

## 작업 인계와 반환

Dispatch에는 다음 정보만 필요한 만큼 전달한다.

- 수행할 작업과 결정할 문제
- 관련 계약·원문의 경로와 절, 필요한 Feature context
- 수정할 정확한 파일과 제외 범위
- 검증 기준과 완료에 필요한 evidence

새 agent는 도구가 지원하면 `fork_turns="none"`으로 시작하여 필요한 문맥만 전달한다.
연속 수정은 기존 agent에 짧은 후속 작업으로 보낸다. 같은 문맥에서 읽은 변경 없는 자료를
다시 읽거나 모든 Feature 문서를 매번 주입하지 않는다.

Return은 결과·판단, 변경 파일, 실행한 명령·exit code·결정적 결과, 미해결 항목·제한을
간결하게 전달한다. 고정 envelope, outcome enum, retry signature나 artifact hash를 모든
작업에 요구하지 않는다. 추적에 필요한 계약 revision과 실제 evidence 경로는 남기고,
긴 로그·유도·schema는 원본을 연결한다.

## 구현·검증과 완료

동작 변경에는 그 동작을 확인하는 테스트를 추가·수정하고, 버그는 가능한 경우 실패를
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor나 문서 수정에는
형식적인 새 테스트를 요구하지 않는다.

변경 중에는 관련 검사를 실행한다. 솔버 기능 완료 시, 사용자가 요청한 경우 또는 영향이
넓어 필요한 경우 구성된 전체 build/test를 한 번 수행한다. 기능 완료에 필요한 reference
비교도 수행하며 이후 변경·실패가 없으면 같은 검사를 반복하지 않는다. 문서 작업은 정적
검토로 확인하고 build/test를 실행하지 않는다.

메인은 완료를 판단할 때 다음을 확인한다.

- 해당 요구와 계약을 지지하는 실제 결과가 있고 stale/missing evidence가 아님
- 수치 변경에 필요한 독립 검토, analytical/invariant와 물리 검증이 있음
- Reference quantity, unit, coordinate/component와 source identity가 대응함
- Missing, extra, duplicate와 nonfinite required value를 tolerance 전에 거부함
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature 판정 기준을 유지함
- 실제 명령·exit code·판정값과 가정·미지원 범위·잔여 위험을 재현 가능하게 기록함

Reference artifact와 상위 계약을 구현 결과에 맞춰 생성·보정하거나 tolerance를 완화하지
않는다. 실패·미실행 검사를 통과로 표시하지 않으며 과거 통과를 현재 검증으로 소급하지 않는다.

## 실패 처리와 사용자 결정

일반 구현 실패는 현재 구현 owner가 재현·수정하고 관련 검사를 수행한다. 새 근거나 변경
없이 같은 명령·agent 호출을 반복하지 않는다. 다른 관점이 필요할 때만 원인과 관련 evidence를
전문가에게 전달한다. 고정 correction 횟수나 transport 재시도 예산을 두지 않는다.

상위 계약 결함은 정확한 계약 owner와 경로를 메인에 알린다. Downstream이 요구사항·수식·
schema·tolerance·reference를 바꾸어 실패를 숨기지 않는다. 실제 계약 변경은 영향받은
evidence를 다시 확인하고, 환경 문제는 필요한 환경 변화와 재개 조건을 기록한다.

승인된 범위 안의 되돌릴 수 있는 저장소 작업에는 반복적인 중간 승인 절차를 추가하지 않는다.
계획 요청만으로 실행 권한을 추정하지 않으며 다음 결정이 실제로 필요할 때 사용자에게
대안·권고·영향을 함께 제시한다.

- 지원 physics·제품 범위·공개 호환성의 변경
- 지배 방정식·정식화·재료 모델 등 물리적 의미의 선택
- 합격/불합격이나 공개 정확도 약속을 바꾸는 acceptance·tolerance 선택
- Authoritative 입력·영속 결과 schema의 비호환 변경이나 해결되지 않은 필수 계약/reference 충돌
- 외부 solver의 라이선스·자격증명·비공개 자료·비용 또는 외부 협조
- 중대한 보안·신뢰 경계 변경이나 해결되지 않은 보안·법률·라이선스 위험 수용
- 파괴적 Git/파일 작업, push·tag·publish·deploy·package·release

내부 검증 또는 readiness 권고는 외부 실행 권한이 아니다. 이미 승인된 작업의 일반 문서
작성·로컬 실행·인계마다 승인을 다시 요구하지 않는다.

## 언어와 기록

기능 문서는 기본적으로 한국어 Markdown으로 작성한다. Agent/skill ID, field,
requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은
`FEM-REQ-<FEATURE>-###`이다. 보고서는 실제 결정과 evidence를 한 번만 기록하고,
기존 phase·coordination·실패 기록은 이력으로 보존한다.