FESADev/docs/coordination/README.md

# Coordination Report 문서 작성 가이드

이 디렉터리는 Coordinator Agent가 작성하거나 제안하는 기능별 workflow coordination report를 보관하는 위치다.

Coordinator Agent는 FESA solver 기능 개발의 전체 lifecycle에서 gate evidence, handoff, rework loop, blocker, user decision을 관리한다. 이 Agent는 specialist agent의 기술 판정을 대체하지 않고, 다음 agent가 어떤 입력으로 무엇을 산출해야 하는지 명확히 기록한다.

기본 문서명은 `docs/coordination/<feature-id>-coordination.md` 형식을 사용한다.

## Coordinator Agent 역할

수행한다:
- feature request를 `feature_id`, target capability, initial priority, expected first agent로 분류한다.
- existing docs/reports/artifacts를 읽고 workflow state를 audit한다.
- gate별 source evidence, missing evidence, contradictory evidence를 inventory로 만든다.
- 다음 agent handoff package를 작성한다.
- repeated failure와 blocker를 추적하고 escalation target을 정한다.
- final workflow closure를 기록한다.

수행하지 않는다:
- source code를 수정하지 않는다.
- tests를 수정하지 않는다.
- CMake files 또는 build configuration을 수정하지 않는다.
- build/test validation을 실행하지 않는다.
- reference comparison을 실행하지 않는다.
- physics evaluation을 실행하지 않는다.
- requirements, formulations, I/O contracts, numerical review reports를 수정하지 않는다.
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
- reference CSV를 생성하지 않는다.
- subagents를 자동 spawn하지 않는다.
- release readiness를 독립적으로 승인하지 않는다.

## 실행 순서

Coordinator Agent는 다음 순서를 따른다.

```text
INTAKE -> STATE AUDIT -> GATE DECISION -> HANDOFF PACKAGE -> STATUS REPORT
```

`STATE AUDIT`에서는 다음 evidence를 확인한다.

- Requirement Agent output
- Research Agent output
- Formulation Agent output
- Numerical Review Agent output
- I/O Definition Agent output
- Reference Model Agent output
- Implementation Planning Agent output
- Implementation Agent report
- Build/Test Executor Agent report
- Correction Agent report
- Reference Verification Agent report
- Physics Evaluation Agent report
- Release Agent report
- validation command evidence: `python scripts/validate_workspace.py`

## 문서 템플릿

```markdown
# <feature title> Coordination Report

## Metadata
- feature_id: <feature-id>
- status: intake | needs-requirements | needs-research | needs-formulation | needs-numerical-review | needs-io-definition | needs-reference-model | needs-implementation-plan | ready-for-implementation | needs-build-test | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-release | ready-for-release | completed | needs-user-decision | blocked
- owner_agent: coordinator-agent
- date: <YYYY-MM-DD>
- source_docs: <docs/reports used>

## Feature Request Summary
- requested_feature: <short summary>
- current_goal: <current coordination goal>
- included_scope: <included scope>
- excluded_scope: <excluded scope>
- priority: <initial priority>

## Current Workflow State

| item | value | notes |
| --- | --- | --- |
| current_gate | <gate> | <notes> |
| completed_outputs | <outputs> | <notes> |
| missing_outputs | <outputs> | <notes> |
| active_blockers | <blockers> | <notes> |
| next_eligible_gate | <gate> | <notes> |

## Gate Evidence Inventory

| gate | owning_agent | expected_evidence | observed_evidence | status | notes |
| --- | --- | --- | --- | --- | --- |
| requirements | Requirement Agent | docs/requirements/<feature-id>.md | <path/status> | pass | fail | missing | <notes> |
| research | Research Agent | docs/research/<feature-id>-research.md | <path/status> | pass | fail | missing | <notes> |
| formulation | Formulation Agent | docs/formulations/<feature-id>-formulation.md | <path/status> | pass | fail | missing | <notes> |
| numerical_review | Numerical Review Agent | docs/numerical-reviews/<feature-id>-review.md | <path/status> | pass | fail | missing | <notes> |
| io_definition | I/O Definition Agent | docs/io-definitions/<feature-id>-io.md | <path/status> | pass | fail | missing | <notes> |
| reference_model | Reference Model Agent | docs/reference-models/<feature-id>-reference-models.md | <path/status> | pass | fail | missing | <notes> |
| implementation_planning | Implementation Planning Agent | docs/implementation-plans/<feature-id>-implementation-plan.md | <path/status> | pass | fail | missing | <notes> |
| implementation | Implementation Agent | implementation report | <path/status> | pass | fail | missing | <notes> |
| build_test | Build/Test Executor Agent | pass-for-reference-verification | <path/status> | pass | fail | missing | <notes> |
| correction | Correction Agent | correction report when needed | <path/status> | pass | fail | missing | <notes> |
| reference_verification | Reference Verification Agent | pass-for-physics-evaluation | <path/status> | pass | fail | missing | <notes> |
| physics_evaluation | Physics Evaluation Agent | pass-for-release-agent | <path/status> | pass | fail | missing | <notes> |
| release | Release Agent | ready-for-release | <path/status> | pass | fail | missing | <notes> |

## Decision Log

| date | decision_type | decision | source_evidence | rationale |
| --- | --- | --- | --- | --- |
| <YYYY-MM-DD> | gate transition | blocker | user decision | rework decision | <decision> | <path/status> | <reason> |

## Next Agent Handoff

| field | value |
| --- | --- |
| target_agent | <agent name> |
| reason | <why this agent is next> |
| required_inputs | <docs/reports/artifacts> |
| expected_output | <expected report or artifact contract> |
| acceptance_gate | <status or gate required after handoff> |
| stop_condition | <when the agent should stop and hand back> |
| missing_evidence | <missing inputs or decisions> |

## Traceability Snapshot

| requirement_id | gate | report | artifact | status | current_disposition |
| --- | --- | --- | --- | --- | --- |
| <req-id> | <gate> | <report path> | <artifact path> | <status> | <released | deferred | blocked | pending> |

## Risk and Blocker Register

| risk_or_blocker | category | owner | status | next_action |
| --- | --- | --- | --- | --- |
| <issue> | upstream ambiguity | repeated failure | reference artifact gap | environment blocker | <agent/user> | open | mitigated | blocked | <action> |

## Rework Loop Control

| failure_classification | correction_attempt_count | escalation_target | stop_condition | notes |
| --- | --- | --- | --- | --- |
| <classification> | <count> | <agent/user> | <condition> | <notes> |

## No-Change Assertion
- source_files_modified: false
- test_files_modified: false
- cmake_files_modified: false
- reference_artifacts_modified: false
- tolerance_policies_modified: false
- notes: <observed no-change evidence or exception>

## Open Issues
- <unresolved user decision, missing evidence, contradictory report, or blocked transition>
```

## 상태 값

- `intake`: 기능 요청은 들어왔지만 첫 handoff가 완료되지 않았다.
- `needs-requirements`: Requirement Agent가 요구조건을 정의하거나 수정해야 한다.
- `needs-research`: Research Agent가 source-backed research evidence를 제공하거나 수정해야 한다.
- `needs-formulation`: Formulation Agent가 FEM 정식화를 작성하거나 수정해야 한다.
- `needs-numerical-review`: Numerical Review Agent가 정식화를 검토하거나 재검토해야 한다.
- `needs-io-definition`: I/O Definition Agent가 Abaqus input/output 계약을 정의하거나 수정해야 한다.
- `needs-reference-model`: Reference Model Agent가 reference model artifacts를 정의하거나 수정해야 한다.
- `needs-implementation-plan`: Implementation Planning Agent가 TDD implementation plan을 작성하거나 수정해야 한다.
- `ready-for-implementation`: implementation plan이 준비되었고 downstream 구현을 막는 upstream gate가 없다.
- `needs-build-test`: 구현 이후 독립 Build/Test Executor 검증이 필요하다.
- `needs-correction`: implementation-owned failure가 있어 Correction Agent가 필요하다.
- `needs-reference-verification`: Build/Test evidence가 `pass-for-reference-verification`이다.
- `needs-physics-evaluation`: Reference Verification report가 `pass-for-physics-evaluation`이다.
- `needs-release`: Physics Evaluation report가 `pass-for-release-agent`이다.
- `ready-for-release`: Release Agent report가 `ready-for-release`이고 final closure 기록이 필요하다.
- `completed`: Release Agent report가 `ready-for-release`이고 Coordinator가 final workflow closure를 기록했다.
- `needs-user-decision`: 사용자 또는 project decision 없이는 안전하게 진행할 수 없다.
- `blocked`: 사용자 결정, 환경 변경, upstream correction 없이는 진행할 수 없다.

## Handoff 원칙

- 다음 단계 handoff는 source evidence, missing evidence, expected output, acceptance gate, stop condition을 포함해야 한다.
- specialist agent가 소유한 기술 판정을 Coordinator가 대체하지 않는다.
- `ready-for-implementation`은 Implementation Planning report가 `ready-for-implementation`일 때만 가능하다.
- `needs-reference-verification`은 Build/Test evidence가 `pass-for-reference-verification`일 때만 가능하다.
- `needs-physics-evaluation`은 Reference Verification report가 `pass-for-physics-evaluation`일 때만 가능하다.
- `needs-release`는 Physics Evaluation report가 `pass-for-release-agent`일 때만 가능하다.
- `completed`는 Release Agent report가 `ready-for-release`이고 final workflow closure가 기록된 경우에만 가능하다.
- 동일 failure classification이 두 번 이상 반복되거나 upstream 계약 변경이 필요하면 `needs-user-decision` 또는 `blocked`로 전환한다.

## 검증 기준

- Coordinator Agent config와 문서 템플릿 검증은 Python unittest로 수행한다.
- workspace 검증은 `python scripts/validate_workspace.py`를 사용한다.
- 현재 repository에 CMake 프로젝트가 없으면 harness 정책에 따라 no-CMake validation 경로가 성공으로 기록될 수 있다.