FESADev/docs/coordination

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 HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
• subagents를 자동 spawn하지 않는다.
• release readiness를 독립적으로 승인하지 않는다.

실행 순서

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

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

문서 템플릿

# <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 경로가 성공으로 기록될 수 있다.