initial commit

docs/coordination/README.md

@@ -0,0 +1,189 @@
+# 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 경로가 성공으로 기록될 수 있다.