FESADev/docs/SOLVER_AGENT_DESIGN.md

# Structural FEM Solver Agent Design

## 1. 목적

이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
산출물만 소유한다. 기능별 문서는 `docs/<feature-id>/`에 보존한다.
폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는
[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다.

이 계약의 목표는 다음과 같다.

- 수치적·물리적 책임을 명확히 분리한다.
- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다.
- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다.
- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다.
- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다.

## 2. 권한과 판단 기준

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

1. 사용자가 승인한 feature contract와 critical decision
2. 지배 방정식, 수학적 일관성, 적용되는 표준과 검증된 1차 문헌
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 verification 사례
4. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md`와 기존 승인 계약
5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현

Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석
절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료
구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다.
관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다.

공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이
입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로
진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다.

## 3. 계층과 단독 상태 전이

`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다.

```text
INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
```

- Coordinator는 요구사항 접수 시 Feature 폴더와 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`,
  `coordination.md`를 생성하고 문서 목록과 참조를 관리한다. 프로젝트 기준 문서는 보존한다.
- Coordinator만 `docs/<feature-id>/coordination.md`의 현재 stage, outcome과 next owner를 바꾼다.
- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다.
- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다.
- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한
  후 기록한다.
- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다.
- 누락된 증거는 통과로 간주하지 않는다.

## 4. 단계와 소유권

| Stage | Owner | Owned outputs |
| --- | --- | --- |
| intake / coordination | `coordinator-agent` | `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md` |
| `requirements` | `requirement-agent` | `requirements.md` |
| `research` | `research-agent` | `research.md` |
| `formulation` | `formulation-agent` | `formulation.md` |
| `numerical-review` | `numerical-review-agent` | `numerical-review.md`, `reference-model.md` |
| `io-definition` | `io-definition-agent` | `io.md` |
| `implementation-planning` | `implementation-planning-agent` | `implementation-plan.md`, assigned Harness phase files |
| `implementation` | `implementation-agent` | implementation files, tests, build registration, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
| `physics-evaluation` | `physics-evaluation-agent` | `physics-evaluation.md` |
| `release-readiness` | `release-agent` | `release.md` |

`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
implementation-owned 파일과 `corrections.md`를 수정한다.

문서 경로는 모두 `docs/<feature-id>/` 기준이다. 각 specialist는 자신의 기본 산출물에
연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며
specialist 본문의 편집 권한을 뜻하지 않는다.

각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.

## 5. 공통 handoff envelope

모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
envelope에는 전이에 필요한 요약만 둔다.

```yaml
feature_id: <stable feature id>
stage: requirements | research | formulation | numerical-review | io-definition |
  implementation-planning | implementation | correction | physics-evaluation |
  release-readiness
outcome: pass | return-upstream | retry | blocked-environment | needs-user-decision
next_owner: <agent id or null>
evidence_paths: [<repository-relative path>]
evidence_digest: <commands, exit codes, decisive findings, artifact hashes when relevant>
failure_classification: <normalized class or null>
retry_key: <feature-id|failing-gate|classification|contract-revision or null>
attempt: <nonnegative integer>
escalation_class: <critical class or null>
blocker: <actionable blocker or null>
```

필드 규칙은 다음과 같다.

- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다.
- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다.
- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다.
- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다.
- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다.
- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다.
- Dispatch는 `docs/<feature-id>/`와 Feature 관리 문서 3개를 필수 입력으로 명시한다.
  기본·상세 산출물의 owner를 지정하고 반환된 상세 문서도 `evidence_paths`로 확인한다.

## 6. Outcome과 전이 규칙

| Outcome | 의미 | Coordinator action |
| --- | --- | --- |
| `pass` | 현재 owner의 gate evidence가 완전함 | 다음 정규 stage로 전이 |
| `return-upstream` | 선행 계약의 수정이 필요함 | `next_owner`로 되돌리고 영향받은 downstream gate를 stale 처리 |
| `retry` | 계약을 바꾸지 않는 bounded rerun이 가능함 | retry 정책 안에서 지정 owner를 재호출 |
| `blocked-environment` | 도구·권한·의존성·라이선스 문제로 신뢰성 있는 진행 불가 | 상태를 보존하고 환경 수정 전까지 중단 |
| `needs-user-decision` | 아래 critical decision이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 |

`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지
않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만
사용한다.

정규 통과 순서는 다음과 같다.

```text
requirements -> research -> formulation -> numerical-review -> io-definition
-> implementation-planning -> implementation -> physics-evaluation
-> release-readiness -> completed
```

Numerical review는 formulation correctness와 reference-model readiness가 모두 확보되어야
`pass`할 수 있다. Implementation은 TDD evidence, 전체 build/test와 feature가 요구하는
reference comparison이 모두 통과해야 `pass`할 수 있다. Release의 `pass`는 내부 readiness
closure일 뿐 publish, deploy, push, tag 또는 package 권한이 아니다.

## 7. 자율 진행과 사용자 escalation

Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다.

- 승인 계약을 구현하는 파일 배치, private API와 내부 자료구조 선택
- 기존 규칙에 따른 테스트 분해, config-selected build/test backend 등록, 진단 문구와 오류 처리
- 문서·계획·evidence report의 생성 및 갱신
- 명백한 compile, link, test, parser와 implementation defect의 최소 수정
- Numerical Review가 `docs/TOLERANCE.md`와 feature evidence에 따라 선택하는 비교 quantity,
  identity/component, metric, scale, blocking/diagnostic 구분과 수치 tolerance
- 공식 문서와 저장소 관례가 하나의 의미를 정하는 secondary convention
- 안전한 read-only 조사, local build/test와 저장된 reference artifact 비교

다음 항목만 `needs-user-decision`으로 escalation한다.

- feature scope, 지원 해석 유형 또는 공개 호환성의 변경
- 지배 방정식, 요소 정식화, 재료 모델, 접촉·동역학 등 물리적 의미의 선택
- 합리적인 두 acceptance 기준이 동일 evidence를 pass와 fail로 나누고 그 선택이 제품
  acceptance 의미나 공개 정확도 약속을 바꾸는 경우
- authoritative input/output schema나 영속 public contract의 비호환 변경
- authoritative requirement와 reference evidence가 충돌하고 기술 evidence로 우선순위를
  결정할 수 없는 경우
- 외부 solver 실행에 필요한 라이선스·자격증명·비공개 자료
- 보안·신뢰 경계 또는 credential 처리의 중대한 변경, 해결되지 않은 보안·법률·라이선스
  위험의 수용
- destructive Git 작업, 외부 게시, push, tag, deploy, package 또는 release

질문은 결정 가능한 대안, downstream 영향과 권고안을 하나로 묶는다. 단순 진행 확인,
일반 문서 승인, 계획 승인 또는 agent 간 handoff 승인을 반복해서 요청하지 않는다.

## 8. 실패 분류와 유한 correction

실패 분류는 최소한 다음 값을 정규화해 사용한다.

```text
configure | compile | link | test | reference-comparison | harness |
environment | upstream-contract | physics | evidence
```

Coordinator는 다음 요소로 retry signature를 만든다.

```text
retry_key = feature_id | failing_gate | normalized_failure_classification | contract_revision
```

동일 `retry_key`에 대한 Correction loop는 한 번만 허용한다.

1. Implementation Agent가 실패를 분류하고 명백한 implementation-owned defect를 최소 수정·재검증한다.
2. 반복되거나 원인이 불명확하면 Coordinator가 해당 key의 correction 사용 이력을 확인한다.
3. 사용 이력이 없을 때만 Correction Agent를 한 번 dispatch한다.
4. Correction Agent는 `retry`로 Implementation rerun을 요청하고 Coordinator가 rerun을 dispatch한다.
5. 같은 key가 다시 실패하면 두 번째 correction을 금지한다. 계약 문제는 `return-upstream`,
   환경 문제는 `blocked-environment`, 실제 critical choice만 `needs-user-decision`으로 전환한다.

문구만 바꾸거나 동일 계약 revision을 새 key로 가장하면 안 된다. Upstream 계약이 승인된 방식으로
변경된 경우에만 `contract_revision`을 올리고 새 signature를 만든다.

## 9. Evidence gate

Coordinator는 `pass` 전에 다음을 확인한다.

- 요구되는 산출물이 존재하고 owner가 명시되어 있다.
- 선행 artifact와 revision이 일치하며 stale evidence가 아니다.
- 실행 증거에는 실제 명령, 종료 코드, 핵심 결과가 있다.
- 수치 비교에는 quantity, unit, coordinate/component, matching rule과 적용 tolerance가 있다.
- reference row의 missing, extra, duplicate와 nonfinite 값은 tolerance 판정 전에 검출된다.
- 가정, 미지원 범위와 잔여 위험이 기록되어 있다.
- specialist owner의 결론을 Coordinator나 downstream agent가 대신 만들지 않았다.
- Feature 문서 목록과 기본·상세 문서 링크가 유효하고 필수 상세 근거까지 검토되었다.

Reference input과 결과 artifact는 명시적으로 소유 agent가 아닌 한 read-only다. 저장된 외부
reference 결과를 임의로 생성·보정하거나 통과하도록 수치를 변경해서는 안 된다.

## 10. 언어와 기록

- 기능 문서는 사용자가 다른 언어를 요청하지 않는 한 한국어 Markdown으로 작성한다.
- Agent id, field name, outcome, failure classification, requirement id, path와 command는 English를 유지한다.
- Requirement id 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
- Placeholder artifact는 만들지 않는다. Correction이 실제 발생할 때만 `corrections.md`를 만든다.
- 모든 stage는 자신이 변경한 경로와 변경하지 않은 upstream contract를 명확히 기록한다.