docs: align guidance with simplified agent and harness workflow

docs/SOLVER_AGENT_DESIGN.md

@@ -1,220 +1,135 @@
 # Structural FEM Solver Agent Design
 
-## 1. 목적
+## 목적
 
-이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
-`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
-산출물만 소유한다. 기능별 문서는 `docs/<feature-id>/`에 보존한다.
-폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는
-[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다.
+메인 assistant가 작업 분해, 필요한 specialist 선택, 구현 조정과 완료 확인을 담당한다.
+작은 문서·구현·일상 결함은 직접 처리한다. Specialist는 전문 판단이나 독립 검토가
+필요한 bounded task에 사용하며 고정 lifecycle을 순회하기 위해 호출하지 않는다.
 
-이 계약의 목표는 다음과 같다.
+현재 운영 결정은 [ADR-028](ADR.md#adr-028), Feature 폴더와 산출물 관리는
+[FEATURE_DOCUMENTATION](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`와 기존 승인 계약
+1. 현재 사용자 요청의 범위·권한과 승인된 Feature contract·critical decision
+2. 지배 방정식, 수학적 일관성, 적용 표준과 검증된 1차 문헌
+3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 검증 사례
+4. 프로젝트 지침, architecture, ADR, tolerance와 기존 승인 계약
 5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현
 
-Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석
-절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료
-구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다.
-관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다.
+Abaqus는 외부 reference convention이다. 지원 subset의 공개 입력 의미와 승인된 비교량을
+참고하되 비공개 알고리즘·내부 상태·결과 생성 절차를 추정하거나 내부 동등성을 주장하지
+않는다. 수치 결과의 exact equality는 허용되지만 내부 동등성의 evidence가 아니다.
+의미상 무해하다고 계약된 항목만 명시적 warning/no-op으로 처리하고 그 밖의 미지원
+semantics는 fail-closed로 진단한다.
 
-공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이
-입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로
-진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다.
+## 메인의 작업 조정
 
-## 3. 계층과 단독 상태 전이
+메인은 관련 계약과 현재 evidence를 확인하여 작업·수정 파일·검증 기준을 정한다.
+새 Feature에 지속할 계약이나 근거가 필요하면 `docs/<feature-id>/`를 초기화하고
+`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 작은 수정에는 새 Feature 폴더나
+빈 보고서를 만들지 않는다. 현재 checklist는 PRD 한 곳에 둔다.
 
-`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다.
+메인은 계획·구현·일반 실패 수정을 직접 수행하거나 필요한 구현 묶음을 위임할 수 있다.
+Specialist는 할당된 판단과 파일만 소유하며 다른 계약을 수정하거나 peer를 재위임하지
+않는다. 메인은 결과를 확인하되 독립 검토가 필요한 판단을 작성자의 자기 승인으로 대체하지
+않는다. 누락된 evidence는 통과가 아니다.
 
-```text
-INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
-```
+## Specialist 선택
 
-- 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 판단을 대신하지 않는다.
-- 누락된 증거는 통과로 간주하지 않는다.
+현재 profile은 [`.codex/agents`](../.codex/agents)에 있다.
 
-## 4. 단계와 소유권
-
-| Stage | Owner | Owned outputs |
+| Specialist | 호출할 때 | 기본 추론 강도 |
 | --- | --- | --- |
-| 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` |
+| `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` |
 
-`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
-implementation-owned 파일과 `corrections.md`를 수정한다.
+수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review를 수행한다.
+역할의 조건부 호출은 해당 analytical/invariant 검증이나 계약상 필수 물리·reference
+검증을 생략할 근거가 아니다. Release-readiness 감사는 사용자 명시 요청 시에만
+`fem-release-readiness`로 수행하며 전용 release profile이나 필수 종료 stage를 두지 않는다.
 
-문서 경로는 모두 `docs/<feature-id>/` 기준이다. 각 specialist는 자신의 기본 산출물에
-연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며
-specialist 본문의 편집 권한을 뜻하지 않는다.
+모델과 역할별 강도는 현재 profile을 따른다. 난해한 정식화·수렴 문제에만 필요한 범위에서
+강도를 높인다. Profile 변경만으로 이미 실행 중인 session의 설정이 갱신되었다고 가정하지
+않는다. 불필요한 진행 확인·보고서 재작성·같은 결과의 재검토를 위해 agent를 호출하지 않는다.
 
-각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
-재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
-`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.
+## 작업 인계와 반환
 
-## 5. 공통 handoff envelope
+Dispatch에는 다음 정보만 필요한 만큼 전달한다.
 
-모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
-envelope에는 전이에 필요한 요약만 둔다.
+- 수행할 작업과 결정할 문제
+- 관련 계약·원문의 경로와 절, 필요한 Feature context
+- 수정할 정확한 파일과 제외 범위
+- 검증 기준과 완료에 필요한 evidence
 
-```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>
-```
+새 agent는 도구가 지원하면 `fork_turns="none"`으로 시작하여 필요한 문맥만 전달한다.
+연속 수정은 기존 agent에 짧은 후속 작업으로 보낸다. 같은 문맥에서 읽은 변경 없는 자료를
+다시 읽거나 모든 Feature 문서를 매번 주입하지 않는다.
 
-필드 규칙은 다음과 같다.
+Return은 결과·판단, 변경 파일, 실행한 명령·exit code·결정적 결과, 미해결 항목·제한을
+간결하게 전달한다. 고정 envelope, outcome enum, retry signature나 artifact hash를 모든
+작업에 요구하지 않는다. 추적에 필요한 계약 revision과 실제 evidence 경로는 남기고,
+긴 로그·유도·schema는 원본을 연결한다.
 
-- `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과 전이 규칙
+동작 변경에는 그 동작을 확인하는 테스트를 추가·수정하고, 버그는 가능한 경우 실패를
+재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor나 문서 수정에는
+형식적인 새 테스트를 요구하지 않는다.
 
-| 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이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 |
+변경 중에는 관련 검사를 실행한다. 솔버 기능 완료 시, 사용자가 요청한 경우 또는 영향이
+넓어 필요한 경우 구성된 전체 build/test를 한 번 수행한다. 기능 완료에 필요한 reference
+비교도 수행하며 이후 변경·실패가 없으면 같은 검사를 반복하지 않는다. 문서 작업은 정적
+검토로 확인하고 build/test를 실행하지 않는다.
 
-`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지
-않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만
-사용한다.
+메인은 완료를 판단할 때 다음을 확인한다.
 
-정규 통과 순서는 다음과 같다.
+- 해당 요구와 계약을 지지하는 실제 결과가 있고 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·판정값과 가정·미지원 범위·잔여 위험을 재현 가능하게 기록함
 
-```text
-requirements -> research -> formulation -> numerical-review -> io-definition
--> implementation-planning -> implementation -> physics-evaluation
--> release-readiness -> completed
-```
+Reference artifact와 상위 계약을 구현 결과에 맞춰 생성·보정하거나 tolerance를 완화하지
+않는다. 실패·미실행 검사를 통과로 표시하지 않으며 과거 통과를 현재 검증으로 소급하지 않는다.
 
-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
+일반 구현 실패는 현재 구현 owner가 재현·수정하고 관련 검사를 수행한다. 새 근거나 변경
+없이 같은 명령·agent 호출을 반복하지 않는다. 다른 관점이 필요할 때만 원인과 관련 evidence를
+전문가에게 전달한다. 고정 correction 횟수나 transport 재시도 예산을 두지 않는다.
 
-Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다.
+상위 계약 결함은 정확한 계약 owner와 경로를 메인에 알린다. Downstream이 요구사항·수식·
+schema·tolerance·reference를 바꾸어 실패를 숨기지 않는다. 실제 계약 변경은 영향받은
+evidence를 다시 확인하고, 환경 문제는 필요한 환경 변화와 재개 조건을 기록한다.
 
-- 승인 계약을 구현하는 파일 배치, 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한다.
+- 지원 physics·제품 범위·공개 호환성의 변경
+- 지배 방정식·정식화·재료 모델 등 물리적 의미의 선택
+- 합격/불합격이나 공개 정확도 약속을 바꾸는 acceptance·tolerance 선택
+- Authoritative 입력·영속 결과 schema의 비호환 변경이나 해결되지 않은 필수 계약/reference 충돌
+- 외부 solver의 라이선스·자격증명·비공개 자료·비용 또는 외부 협조
+- 중대한 보안·신뢰 경계 변경이나 해결되지 않은 보안·법률·라이선스 위험 수용
+- 파괴적 Git/파일 작업, push·tag·publish·deploy·package·release
 
-- 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
+내부 검증 또는 readiness 권고는 외부 실행 권한이 아니다. 이미 승인된 작업의 일반 문서
+작성·로컬 실행·인계마다 승인을 다시 요구하지 않는다.
 
-질문은 결정 가능한 대안, 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를 명확히 기록한다.
+기능 문서는 기본적으로 한국어 Markdown으로 작성한다. Agent/skill ID, field,
+requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은
+`FEM-REQ-<FEATURE>-###`이다. 보고서는 실제 결정과 evidence를 한 번만 기록하고,
+기존 phase·coordination·실패 기록은 이력으로 보존한다.