docs: group solver evidence by feature
This commit is contained in:
KOKO\Mimi
@@ -1,160 +0,0 @@
|
||||
# Build/Test Report 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Build/Test Executor Agent가 작성하거나 제안하는 기능별 build/test 실행 리포트를 보관하는 위치다.
|
||||
|
||||
Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 C++/MSVC/CMake/CTest 검증을 실행하고, 실패를 분류해 다음 agent로 handoff한다. 이 agent는 source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다. 기본 build artifact는 `.harness/build/` 아래 생성된다.
|
||||
|
||||
기본 문서명은 `docs/build-test-reports/<feature-id>-build-test.md` 형식을 사용한다.
|
||||
|
||||
## Build/Test Executor Agent 역할
|
||||
|
||||
수행한다:
|
||||
- `.harness/config.json`과 프로젝트 자동 감지 결과를 확인하고 같은 build/test 경로를 독립 실행한다.
|
||||
- implementation plan/report에 명시된 feature-specific CTest를 전체 검증 전에 실행한다.
|
||||
- Harness Python, Hook, agent config 변경이 포함되면 `uv run --with pytest python -m pytest -v -rs`를 실행한다.
|
||||
- CMake preset, 직접 MSBuild, 기본 CMake/MSVC x64 Debug 중 어떤 검증 경로가 사용되었는지 기록한다.
|
||||
- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
|
||||
- command, exit code, duration, stdout/stderr tail, failed test name을 요약한다.
|
||||
- 실패 원인에 따라 Implementation Agent, Correction Agent, Reference Verification Agent, Implementation Planning Agent 중 handoff 대상을 제안한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- source code를 수정하지 않는다.
|
||||
- tests를 수정하지 않는다.
|
||||
- CMake files를 수정하지 않는다.
|
||||
- requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다.
|
||||
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
|
||||
- 최종 reference verification report를 작성하지 않는다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
기본 순서는 implementation plan/report에 따라 다음 중 필요한 항목을 실행한다.
|
||||
|
||||
```powershell
|
||||
cmake -S . -B .harness/build -A x64
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
|
||||
ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Harness Python, Hook, agent config 변경이 검증 범위에 포함되면 다음 명령을 먼저 실행한다.
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -m pytest -v -rs
|
||||
```
|
||||
|
||||
프로젝트 선택 우선순위는 다음과 같다.
|
||||
|
||||
1. `.harness/config.json`의 명시적 `projectType`
|
||||
2. 루트의 CMake metadata
|
||||
3. 루트의 단일 `.sln`
|
||||
4. 루트의 단일 `.vcxproj`
|
||||
|
||||
기본 CMake/MSVC x64 Debug 명령은 다음과 같다.
|
||||
|
||||
```powershell
|
||||
cmake -S . -B .harness/build -A x64
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
CMake preset을 사용하면 configure/build/test preset과 `binaryDir`를 모두
|
||||
`.harness/config.json`에 지정한다. 직접 MSBuild는 solution/project와
|
||||
`msbuild.testCommand`를 지정한다. C/C++와 build metadata가 모두 없으면 검증 대상이
|
||||
없으므로 통과하지만, C/C++ 파일만 있고 build metadata가 없으면 오류다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Build/Test Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_implementation_report: <path or N/A>
|
||||
- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
|
||||
- status: pass-for-reference-verification | needs-correction | needs-environment-fix | needs-upstream-decision | blocked
|
||||
- owner_agent: build-test-executor-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Execution Environment
|
||||
- os: <OS and version>
|
||||
- generator: Visual Studio 17 2022 | <observed generator>
|
||||
- platform: x64 | <observed platform>
|
||||
- config: Debug | <observed config>
|
||||
- build_dir: .harness/build | <configured/observed build dir>
|
||||
- harness_config: .harness/config.json | absent-defaults
|
||||
- project_selection: configured cmake | configured msbuild | auto CMake | auto MSBuild | no C/C++ project
|
||||
- command_discovery_path: CMake preset | direct MSBuild | default CMake/MSVC x64 Debug | no C/C++ project
|
||||
|
||||
## Command Log Summary
|
||||
|
||||
| order | command | exit_code | duration | stdout_stderr_tail |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | uv run --with pytest python -m pytest -v -rs (when applicable) | <code or skipped> | <duration> | <tail summary> |
|
||||
| 2 | <config-resolved configure/build commands> | <code> | <duration> | <tail summary> |
|
||||
| 3 | <feature-specific test command when applicable> | <code or skipped> | <duration> | <tail summary> |
|
||||
| 4 | <config-resolved test discovery/full test commands> | <code> | <duration> | <tail summary> |
|
||||
|
||||
## Validation Results
|
||||
|
||||
| validation_stage | result | evidence |
|
||||
| --- | --- | --- |
|
||||
| harness self-test | pass | fail | skipped | <summary> |
|
||||
| configure | pass | fail | skipped | <summary> |
|
||||
| build | pass | fail | skipped | <summary> |
|
||||
| CTest | pass | fail | skipped | <summary> |
|
||||
| feature-specific tests | pass | fail | skipped | <summary> |
|
||||
|
||||
## Failure Classification
|
||||
|
||||
- classification: configure | compile | link | test | reference-comparison | harness | environment | upstream-contract | N/A
|
||||
- primary_failure: <short reason>
|
||||
- first_failed_command: <command or N/A>
|
||||
- evidence_tail: <short excerpt or summary>
|
||||
|
||||
## Failed Test Inventory
|
||||
|
||||
| test_name | label | command | failure_summary |
|
||||
| --- | --- | --- | --- |
|
||||
| <test name> | <label or N/A> | <command> | <summary> |
|
||||
|
||||
## Handoff Recommendation
|
||||
|
||||
| target_agent | reason | required_input |
|
||||
| --- | --- | --- |
|
||||
| Implementation Agent | <when implementation-owned failure is found> | <command log and failing test> |
|
||||
| Correction Agent | <when focused repair/rollback is needed> | <failure classification and changed files from implementation report> |
|
||||
| Reference Verification Agent | <when build/test passes and reference comparison report is next> | <passing command evidence> |
|
||||
| Implementation Planning Agent | <when plan/test contract is incomplete> | <missing or contradictory plan item> |
|
||||
|
||||
## No-Change Assertion
|
||||
- source_files_modified: false
|
||||
- test_files_modified: false
|
||||
- cmake_files_modified: false
|
||||
- reference_artifacts_modified: false
|
||||
- notes: <observed no-change evidence or exception>
|
||||
|
||||
## Open Issues
|
||||
- <environment gap, missing CMake preset, missing reference artifact, repeated failure, or upstream-contract issue>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
|
||||
- `pass-for-reference-verification`: build/test 검증이 통과해 Reference Verification Agent로 넘길 수 있다.
|
||||
- `needs-correction`: compile, link, ordinary test, implementation-owned failure가 있어 Correction Agent 또는 Implementation Agent 작업이 필요하다.
|
||||
- `needs-environment-fix`: MSVC, CMake generator, Python, path, permission 등 로컬 환경 문제로 검증이 막혔다.
|
||||
- `needs-upstream-decision`: implementation plan, requirements, formulation, I/O, reference artifact, tolerance policy가 불완전하거나 충돌한다.
|
||||
- `blocked`: 반복 실패 또는 외부 조건 때문에 사용자나 Coordinator Agent 결정 없이는 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 실행 명령과 exit code를 기록해야 한다.
|
||||
- 실패 로그는 전체 원문을 복제하지 않고 마지막 핵심 구간과 실패 원인을 요약한다.
|
||||
- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
|
||||
- C/C++와 build metadata가 모두 없는 상황만 `no C/C++ project` 성공으로 기록한다. C/C++ 파일이 있는데 build metadata가 없으면 `environment` 또는 `configure` 실패로 기록한다.
|
||||
- 성공 판정은 build/test 통과까지만 의미한다.
|
||||
- reference tolerance, physics validation, release readiness는 판정하지 않는다.
|
||||
- upstream 계약 문제는 Implementation Agent에 임의 수정으로 넘기지 않고 적절한 upstream agent로 handoff한다.
|
||||
@@ -1,190 +0,0 @@
|
||||
# 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를 실행하지 않는다.
|
||||
- Abaqus 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
|
||||
- Build/Test report의 `.harness/config.json` 또는 자동 감지 기반 MSVC build/test command evidence
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```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가 lightweight reference-case inventory,
|
||||
required input/CSV presence, source-ID/component matching 또는 tolerance를 정의해야 한다.
|
||||
- `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 검증이 있으면 `uv run --with pytest python -m pytest -v -rs`로 실행한다.
|
||||
- C++ build/test evidence는 `.harness/config.json` 또는 Harness 자동 감지 기본값에 따른 Build/Test report에서 확인한다.
|
||||
- C/C++ 파일과 build metadata가 모두 없을 때만 `no C/C++ project` 성공을 허용한다. C/C++ 파일만 있고 build metadata가 없으면 통과 evidence로 사용하지 않는다.
|
||||
@@ -1,158 +0,0 @@
|
||||
# Correction Report 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Correction Agent가 작성하거나 제안하는 기능별 correction report를 보관하는 위치다.
|
||||
|
||||
Correction Agent는 Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent가 전달한 실패를 triage하고, implementation-owned failure만 최소 수정으로 복구한다. 이 agent는 source, header, test, CMake 수정은 수행할 수 있지만 requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.
|
||||
|
||||
기본 문서명은 `docs/corrections/<feature-id>-correction.md` 형식을 사용한다.
|
||||
|
||||
## Correction Agent 역할
|
||||
|
||||
수행한다:
|
||||
- 실패 로그와 implementation report를 읽고 failure classification을 먼저 확정한다.
|
||||
- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
|
||||
- implementation-owned failure에 한해 source/header/test/CMake를 최소 수정한다.
|
||||
- 수정 후 targeted command를 먼저 실행하고 `.harness/config.json` 또는 자동 감지 기본값에 따른 전체 MSVC build/test를 실행한다.
|
||||
- Harness Python, Hook, agent config 관련 수정에서는 `uv run --with pytest python -m pytest -v -rs`도 실행한다.
|
||||
- 반복 실패 또는 upstream 계약 문제를 Coordinator Agent나 관련 upstream agent로 handoff한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- requirements를 수정하지 않는다.
|
||||
- formulations를 수정하지 않는다.
|
||||
- I/O contracts를 수정하지 않는다.
|
||||
- numerical review reports를 수정하지 않는다.
|
||||
- reference artifacts를 수정하지 않는다.
|
||||
- tolerance policies를 수정하지 않는다.
|
||||
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
|
||||
- 최종 reference verification report 또는 physics validation report를 작성하지 않는다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
Correction Agent는 항상 다음 순서를 따른다.
|
||||
|
||||
```text
|
||||
TRIAGE -> MINIMAL FIX -> VERIFY -> REPORT
|
||||
```
|
||||
|
||||
기본 검증 명령은 다음과 같다.
|
||||
|
||||
```powershell
|
||||
<targeted command that reproduced the failure>
|
||||
cmake -S . -B .harness/build -A x64
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`의 설정을 따른다. Harness
|
||||
Python, Hook, agent config, Python validation behavior가 correction 범위에 포함될 때는
|
||||
`uv run --with pytest python -m pytest -v -rs`도 실행한다. Stop 검증은 응답 종료 전에
|
||||
같은 전체 프로젝트 검증을 다시 수행한다.
|
||||
|
||||
## Failure Classification
|
||||
|
||||
- `configure`: CMake configure, preset, generator, cache setup 실패
|
||||
- `compile`: C++ compilation 실패
|
||||
- `link`: linker, symbol resolution, target dependency 실패
|
||||
- `test`: CTest, unit, integration, parser/I/O, ordinary regression test 실패
|
||||
- `reference-comparison`: 저장된 reference artifact와 deterministic comparison 실패
|
||||
- `harness`: Python Harness test, PreToolUse/Stop Hook, config loading, discovery, adapter validation 실패
|
||||
- `environment`: MSVC, CMake, Python, path, permission, generator, local dependency 문제
|
||||
- `upstream-contract`: requirements, formulation, I/O, reference artifact, tolerance, implementation plan 불일치 또는 누락
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Correction Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_failure_report: docs/build-test-reports/<feature-id>-build-test.md | <reference/physics report path>
|
||||
- source_implementation_report: <path or N/A>
|
||||
- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
|
||||
- status: corrected-for-build-test | corrected-for-reference-verification | needs-build-test-rerun | needs-environment-fix | needs-upstream-decision | blocked
|
||||
- owner_agent: correction-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Failure Triage
|
||||
- classification: configure | compile | link | test | reference-comparison | harness | environment | upstream-contract
|
||||
- first_failed_command: <command>
|
||||
- failed_target_or_test: <target, test, label, or N/A>
|
||||
- evidence_tail: <short relevant tail, not full log>
|
||||
- triage_decision: implementation-owned | environment-owned | upstream-owned | blocked
|
||||
|
||||
## Root Cause Summary
|
||||
- root_cause_type: implementation defect | test defect | CMake registration issue | environment issue | upstream-contract issue
|
||||
- summary: <short explanation>
|
||||
- why_minimal_fix_is_allowed: <contract or failure evidence>
|
||||
|
||||
## Correction Scope
|
||||
|
||||
| file | change_type | reason | in_scope |
|
||||
| --- | --- | --- | --- |
|
||||
| include/fesa/<module>/<file>.hpp | source/header | <reason> | true |
|
||||
| src/<module>/<file>.cpp | source | <reason> | true |
|
||||
| tests/<module>/<file>_test.cpp | test | <reason> | true |
|
||||
| CMakeLists.txt | CMake | <reason> | true |
|
||||
|
||||
Excluded files:
|
||||
- requirements: unchanged
|
||||
- formulations: unchanged
|
||||
- I/O contracts: unchanged
|
||||
- reference artifacts: unchanged
|
||||
- tolerance policies: unchanged
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
| order | command | exit_code | result | evidence |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | <targeted command> | <code> | pass | fail | <summary> |
|
||||
| 2 | <config-resolved full MSVC build/test commands> | <code> | pass | fail | <summary> |
|
||||
| 3 | uv run --with pytest python -m pytest -v -rs | <code or skipped> | pass | fail | skipped | <summary> |
|
||||
|
||||
## Traceability
|
||||
|
||||
| requirement_id | task_id | test_id | failing_command | corrected_file | acceptance_criterion |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| <req-id or N/A> | <task-id or N/A> | <test-id or N/A> | <command> | <file> | <criterion> |
|
||||
|
||||
## Handoff Recommendation
|
||||
|
||||
| target_agent | reason | required_input |
|
||||
| --- | --- | --- |
|
||||
| Build/Test Executor Agent | <independent full validation required> | <commands and correction summary> |
|
||||
| Reference Verification Agent | <reference comparison rerun required> | <corrected-for-reference-verification evidence> |
|
||||
| Physics Evaluation Agent | <physics sanity rerun required> | <corrected solver behavior evidence> |
|
||||
| Implementation Agent | <new implementation task required> | <unfixed implementation gap> |
|
||||
| upstream agent | <contract issue> | <required upstream decision> |
|
||||
| Coordinator Agent | <repeated failure or blocked state> | <classification history and stop condition> |
|
||||
|
||||
## Stop Condition
|
||||
- repeated_failure: true | false
|
||||
- upstream_ambiguity: true | false
|
||||
- reference_artifact_gap: true | false
|
||||
- environment_blocker: true | false
|
||||
- next_required_decision: <decision or N/A>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
|
||||
- `corrected-for-build-test`: correction이 Build/Test Executor Agent 재실행 단계로 넘어갈 수 있다.
|
||||
- `corrected-for-reference-verification`: correction이 Reference Verification Agent 재실행 단계로 넘어갈 수 있다.
|
||||
- `needs-build-test-rerun`: targeted correction은 통과했지만 독립 build/test 재실행이 필요하다.
|
||||
- `needs-environment-fix`: 로컬 toolchain, generator, Python, path, permission 문제가 correction 또는 verification을 막는다.
|
||||
- `needs-upstream-decision`: upstream contract, reference artifact, tolerance, formulation ambiguity가 안전한 수정을 막는다.
|
||||
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 수정 전 failure classification을 기록해야 한다.
|
||||
- 모든 변경은 실패 로그 또는 implementation plan acceptance criterion에 trace되어야 한다.
|
||||
- production C++ 수정에는 관련 테스트 또는 기존 실패 테스트가 있어야 한다.
|
||||
- requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.
|
||||
- 실패 로그는 전체 원문을 복제하지 않고 핵심 tail과 원인 요약만 기록한다.
|
||||
- 동일 classification이 두 번 반복되면 Coordinator Agent 또는 관련 upstream agent로 handoff한다.
|
||||
- 성공 판정은 correction verification까지만 의미한다.
|
||||
- release readiness, reference tolerance success, physics validation success는 판정하지 않는다.
|
||||
@@ -1,148 +0,0 @@
|
||||
# 정식화 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Formulation Agent가 작성하거나 제안한 기능별 유한요소 정식화 문서를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/formulations/<feature-id>-formulation.md` 형식을 사용한다. 각 문서는 Requirement Agent의 요구조건과 Research Agent의 연구 브리프를 입력으로 받아 Implementation Planning Agent와 Implementation Agent가 사용할 수 있는 수학/알고리즘 계약을 제공해야 한다.
|
||||
|
||||
## Formulation Agent 역할
|
||||
|
||||
Formulation Agent는 구현 가능한 FEM 정식화 문서를 작성한다.
|
||||
|
||||
수행한다:
|
||||
- strong form, weak form, discretization을 정리한다.
|
||||
- shape functions, `B` matrix 또는 kinematic operator를 정의한다.
|
||||
- constitutive contract, element residual/internal force, stiffness/tangent matrix를 정리한다.
|
||||
- numerical integration, mapping, Jacobian 규칙을 명시한다.
|
||||
- output recovery, algorithm pseudocode, edge case, numerical risk를 정리한다.
|
||||
- Numerical Review Agent가 검토할 handoff 항목을 남긴다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Formulation
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_research: docs/research/<feature-id>-research.md
|
||||
- status: draft | needs-research | ready-for-numerical-review
|
||||
- owner_agent: formulation-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Scope and Assumptions
|
||||
- analysis_type: linear static | nonlinear static | modal | dynamic | other
|
||||
- element_type: <target element>
|
||||
- deformation: small | large | TBD
|
||||
- linearity: linear | nonlinear | TBD
|
||||
- material_model_boundary: <scope>
|
||||
- coordinate_system: <global/local coordinates>
|
||||
- units: <unit system>
|
||||
|
||||
## Primary Variables and DOFs
|
||||
- nodal_variables: <variables>
|
||||
- dof_ordering: <ordering>
|
||||
- sign_convention: <convention>
|
||||
- constrained_free_dof_assumptions: <assumptions>
|
||||
|
||||
## Strong Form and Boundary Conditions
|
||||
- governing_equation: <equation>
|
||||
- dirichlet_boundary: <essential BC>
|
||||
- neumann_boundary: <natural BC>
|
||||
- natural_boundary_terms: <terms>
|
||||
|
||||
## Weak or Variational Form
|
||||
- test_functions: <definition>
|
||||
- integration_by_parts: <steps>
|
||||
- internal_virtual_work: <expression>
|
||||
- external_virtual_work: <expression>
|
||||
|
||||
## Discretization
|
||||
- interpolation: <field interpolation>
|
||||
- shape_functions: <shape functions>
|
||||
- partition_of_unity_check: <expected check>
|
||||
- kronecker_delta_check: <expected check>
|
||||
- nodal_layout: <layout>
|
||||
|
||||
## Kinematics
|
||||
- strain_displacement_relation: <relation>
|
||||
- B_matrix_or_kinematic_operator: <definition>
|
||||
- deformation_gradient: <definition or N/A>
|
||||
- strain_measure: <definition or N/A>
|
||||
|
||||
## Constitutive Contract
|
||||
- elasticity_matrix_or_stress_update: <contract>
|
||||
- material_state_variables: <variables or N/A>
|
||||
- assumptions_and_constraints: <assumptions>
|
||||
|
||||
## Element Equations
|
||||
- internal_force_or_residual: <expression>
|
||||
- external_force: <expression>
|
||||
- stiffness_or_tangent_matrix: <expression>
|
||||
- mass_or_damping: <required expression or N/A>
|
||||
- vector_matrix_dimensions: <dimensions>
|
||||
|
||||
## Mapping and Numerical Integration
|
||||
- reference_coordinates: <coordinates>
|
||||
- isoparametric_mapping: <mapping>
|
||||
- jacobian: <definition>
|
||||
- determinant_checks: <validity checks>
|
||||
- gauss_points_and_weights: <rule>
|
||||
- integration_policy: full | reduced | selective | analytical | TBD
|
||||
|
||||
## Output Recovery
|
||||
- displacement: <location and convention>
|
||||
- reaction: <calculation>
|
||||
- element_force: <calculation>
|
||||
- strain: <location and recovery>
|
||||
- stress: <location and recovery>
|
||||
- nodal_extrapolation: <policy or N/A>
|
||||
|
||||
## Algorithm Pseudocode
|
||||
```text
|
||||
math-level element routine and assembly flow only
|
||||
no C++ signatures, class names, or file paths
|
||||
```
|
||||
|
||||
## Numerical Risks
|
||||
- rigid_body_modes: <risk/check>
|
||||
- patch_test: <expected test>
|
||||
- symmetry: <expected property>
|
||||
- positive_definiteness: <expected property>
|
||||
- hourglass: <risk or N/A>
|
||||
- shear_locking: <risk or N/A>
|
||||
- volumetric_locking: <risk or N/A>
|
||||
- distortion: <risk/check>
|
||||
- singular_jacobian: <risk/check>
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
|
||||
### Numerical Review Agent
|
||||
- <derivations, assumptions, numerical risks, open issues>
|
||||
|
||||
### I/O Definition Agent
|
||||
- <required inputs, outputs, units, coordinate conventions, output locations>
|
||||
|
||||
### Reference Model Agent
|
||||
- <benchmarkable quantities, patch test needs, expected invariants, edge cases>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <math-level pseudocode, acceptance-relevant quantities, tests to write first>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 요구조건과 연구 브리프에 없는 값을 임의로 확정하지 않는다.
|
||||
- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분한다.
|
||||
- shape functions는 가능한 경우 partition of unity와 Kronecker delta 검사를 포함한다.
|
||||
- numerical integration은 integration point, weight, 적분 대상, full/reduced/selective 정책을 포함한다.
|
||||
- mapping은 reference coordinates, Jacobian, determinant validity check를 포함한다.
|
||||
- output recovery는 nodal, element-level, integration-point 위치를 구분한다.
|
||||
- numerical risk는 rigid body modes, patch test, hourglass, locking, Jacobian 문제를 명시한다.
|
||||
@@ -1,192 +0,0 @@
|
||||
# Implementation Plan 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Implementation Planning Agent가 작성하거나 제안한 기능별 구현계획 문서를 보관하는 위치다.
|
||||
|
||||
Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O
|
||||
정의와 lightweight reference-case inventory를 C++/MSVC 구현 전 TDD 작업계획으로
|
||||
변환한다. Project-local `$harness`를 사용해 multi-Step 초안을 먼저 제시하고 사용자가
|
||||
승인한 뒤에만 `phases/` planning files를 생성한다. 계획과 구현 전에
|
||||
`docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.
|
||||
|
||||
## Harness 실행 handoff
|
||||
|
||||
Planning Agent는 draft -> explicit user approval -> planning files만 수행하며 Step을
|
||||
선택하거나 실행하지 않는다. 별도의 명시적 사용자 요청이 있어야 Executor
|
||||
(`scripts/execute.py`)가 branch, pending Step, retry, timestamps, commits, advancement와 phase
|
||||
status를 소유한다.
|
||||
|
||||
Implementation Agent는 approved plan, materialized phase indexes, Executor-selected current
|
||||
`stepN.md` 하나만 사용한다. current Step에서 `RED -> observed failure -> minimal GREEN ->
|
||||
focused/full VERIFY`를 완료하고 다음 Step을 시작하지 않는다. Agent는 current Step의 `status`
|
||||
및 `summary`, `error_message`, `blocked_reason` payload만 쓴다. `.codex/hooks.json`의
|
||||
PreToolUse와 Stop은 자동으로 실행되며 hook entry point를 수동 실행해 대체하지 않는다.
|
||||
|
||||
기본 파일명은 `docs/implementation-plans/<feature-id>-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다.
|
||||
|
||||
## Implementation Planning Agent 역할
|
||||
|
||||
수행한다:
|
||||
- upstream 문서가 구현 계획에 충분한지 Readiness Check를 수행한다.
|
||||
- 요구조건과 정식화를 작은 Work Breakdown task로 나눈다.
|
||||
- unit, integration, parser/I/O, reference-comparison 테스트를 TDD 순서로 정렬한다.
|
||||
- CMake/CTest target, `add_test`, label, `ctest -C Debug` 검증 계획을 정의한다.
|
||||
- candidate source/header/test/CMake 파일과 ownership boundary를 제안한다.
|
||||
- requirement, task, test, reference model, acceptance criterion을 Acceptance Traceability Matrix로 연결한다.
|
||||
- `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다.
|
||||
- 한 Step을 하나의 layer/module로 제한하고 prerequisite files, RED/GREEN/VERIFY, exact
|
||||
acceptance commands와 구체적 금지사항을 포함한다.
|
||||
- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 승인 뒤에도 planning files만
|
||||
materialize한다. 별도 요청 없이는 `scripts/execute.py`를 실행하지 않으며 Step을
|
||||
선택하거나 실행하지 않는다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 테스트 파일을 작성하지 않는다.
|
||||
- CMake 파일을 수정하지 않는다.
|
||||
- CMake/CTest를 실행하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- solver 결과를 비교하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- C++ API, class name, storage layout, file ownership을 확정하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Implementation Plan
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_research: docs/research/<feature-id>-research.md
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
|
||||
- source_io_definition: docs/io-definitions/<feature-id>-io.md
|
||||
- source_reference_models: docs/reference-models/<feature-id>-reference-models.md
|
||||
- status: draft | needs-upstream-decision | ready-for-implementation | blocked
|
||||
- owner_agent: implementation-planning-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Readiness Check
|
||||
|
||||
| input | required_status | observed_status | decision |
|
||||
| --- | --- | --- | --- |
|
||||
| requirement | approved or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
|
||||
| formulation | pass-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
|
||||
| numerical_review | pass-for-implementation-planning | <status> | proceed | needs-upstream-decision | blocked |
|
||||
| io_definition | ready-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
|
||||
| reference_models | ready-for-implementation-planning or planned artifacts | <status> | proceed | needs-upstream-decision | blocked |
|
||||
|
||||
## Implementation Scope
|
||||
- included_behavior: <behavior to implement>
|
||||
- excluded_behavior: <behavior explicitly out of scope>
|
||||
- non_goals: <items not to design or implement in this phase>
|
||||
|
||||
## Work Breakdown
|
||||
|
||||
| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| TASK-001 | 1 | <small implementation task> | <requirement/formulation/io/reference id> | none | TEST-001 |
|
||||
|
||||
## TDD Test Plan
|
||||
|
||||
| test_id | order | test_type | red_condition | green_condition | linked_task | command |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| TEST-001 | 1 | unit | test fails because behavior is missing | test passes after minimal implementation | TASK-001 | ctest -C Debug -R <test-name> |
|
||||
| TEST-002 | 2 | integration | integrated path fails before implementation | integrated path passes | TASK-002 | ctest -C Debug -R <test-name> |
|
||||
| TEST-003 | 3 | parser/I/O | Abaqus .inp case is not accepted or mapped | input maps to expected semantic model | TASK-003 | ctest -C Debug -R <test-name> |
|
||||
| TEST-004 | 4 | reference-comparison | solver HDF5/CSV view comparison fails before implementation | comparison is within planned tolerance | TASK-004 | ctest -C Debug -R <test-name> |
|
||||
|
||||
## CMake/CTest Plan
|
||||
- target_candidates: <library/test executable targets>
|
||||
- add_test_needs: <CTest registration needs>
|
||||
- labels: unit | integration | reference | parser | io
|
||||
- msvc_config: Debug
|
||||
- expected_feature_command: ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
|
||||
- full_validation_source: .harness/config.json | Harness auto detection
|
||||
|
||||
## Candidate Files and Ownership
|
||||
|
||||
| file_candidate | purpose | owner_boundary | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| include/fesa/<module>/<candidate>.hpp | <candidate public header role> | candidate only, not final API | <notes> |
|
||||
| src/<module>/<candidate>.cpp | <candidate implementation role> | candidate only, not final API | <notes> |
|
||||
| tests/<module>/<candidate>_test.cpp | <test role> | required before production change | <notes> |
|
||||
| CMakeLists.txt | <target/test registration role> | candidate only | <notes> |
|
||||
|
||||
## Data Flow Contract
|
||||
1. Abaqus `.inp` input follows docs/io-definitions/<feature-id>-io.md.
|
||||
2. Parser/I/O path maps model data and history data into the internal semantic model.
|
||||
3. Solver path produces authoritative `results.h5` with displacement, reaction, internal force, stress, or feature-specific result datasets.
|
||||
4. Reference inputs and required CSV files use exact existing paths declared by the feature.
|
||||
5. Reference comparison tests compare only blocking/warning quantities by source ID/component.
|
||||
|
||||
## Acceptance Traceability Matrix
|
||||
|
||||
| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| <req-id> | TASK-001 | TEST-001 | <model-id or N/A> | <criterion> | draft |
|
||||
|
||||
## Validation Commands
|
||||
```powershell
|
||||
cmake -S . -B .harness/build -A x64
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 해석 가능한 명령을 적는다.
|
||||
Harness Python, Hook, agent config 변경이 계획 범위에 포함되면
|
||||
`uv run --with pytest python -m pytest -v -rs`도 추가한다. Stop 검증은 Step 종료 전 전체
|
||||
MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를 대체하지 않는다.
|
||||
|
||||
## Risks and Downstream Handoff
|
||||
|
||||
### Implementation Agent
|
||||
- <task order, tests to write first, candidate files, acceptance criteria>
|
||||
|
||||
### Build/Test Executor Agent
|
||||
- <validation commands, expected CTest labels, feature-specific commands>
|
||||
|
||||
### Correction Agent
|
||||
- <likely failure classifications and upstream rollback guidance>
|
||||
|
||||
### Reference Verification Agent
|
||||
- <planned HDF5/CSV comparison tests, exact case paths, tolerance mapping, source-ID/component matching>
|
||||
|
||||
## Harness Step Draft
|
||||
|
||||
| step | name | owned layer/module | prerequisite files | RED/GREEN/VERIFY | acceptance commands | stop condition |
|
||||
| ---: | --- | --- | --- | --- | --- | --- |
|
||||
| 0 | <kebab-case> | <one scope> | <exact paths> | <test-first sequence> | <exact commands> | <condition> |
|
||||
|
||||
User approval is required before materializing this draft under `phases/`.
|
||||
|
||||
## Executor Handoff
|
||||
|
||||
- Executor authorization: separate explicit user request for `scripts/execute.py`.
|
||||
- implementation input: approved plan, materialized phase indexes, and Executor-selected current
|
||||
`stepN.md`.
|
||||
- implementation recipe: `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`.
|
||||
- metadata ownership: Implementation Agent records only the current Step `status` plus `summary`,
|
||||
`error_message`, or `blocked_reason`; Executor records branch, pending-Step selection, retry,
|
||||
timestamps, commits, advancement, and phase status.
|
||||
- hooks: `.codex/hooks.json` automatically invokes PreToolUse and Stop; never manually run hook
|
||||
entry points as substitutes.
|
||||
|
||||
## Open Issues
|
||||
- <requirement, formulation, I/O, required comparison file/mapping, tolerance, or architecture issue>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` requirement는 최소 하나의 task와 test에 연결되어야 한다.
|
||||
- C++ production 변경마다 선행 테스트 파일 또는 테스트 추가 계획이 있어야 한다.
|
||||
- reference comparison이 필요한 기능은 exact existing input/required CSV path와 FESA
|
||||
HDF5-to-reference-CSV source-ID/component mapping test 계획을 가져야 한다.
|
||||
- Implementation Planning Agent는 Harness Step 초안을 사용자에게 승인받은 뒤에만 phase
|
||||
index와 step files를 생성하며 executor는 자동 실행하지 않는다.
|
||||
- CMake/CTest 계획은 MSVC x64 Debug 검증 경로와 호환되어야 한다.
|
||||
- 구현 계획은 테스트 작성, 실패 확인, 최소 구현, validation 순서를 명시해야 한다.
|
||||
- upstream 문서가 불완전하면 값을 임의로 채우지 않고 `needs-upstream-decision` 또는 `blocked`로 표시한다.
|
||||
- release 완료나 reference tolerance 통과 판정은 하지 않는다.
|
||||
@@ -1,179 +0,0 @@
|
||||
# I/O 정의 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 I/O Definition Agent가 작성하거나 제안한 기능별 입출력 정의 문서를 보관하는 위치다.
|
||||
|
||||
FESA 솔버의 입력 파일은 Abaqus input file이다. 다만 초기 FESA는 Abaqus 전체 문법 호환을 목표로 하지 않고, 기능별로 지원할 Abaqus keyword subset과 내부 모델 매핑을 명확히 정의한다.
|
||||
|
||||
기본 파일명은 `docs/io-definitions/<feature-id>-io.md` 형식을 사용한다. 각 문서는 Requirement Agent, Formulation Agent, Numerical Review Agent의 산출물을 입력으로 받아 Abaqus `.inp` 입력 계약, authoritative HDF5 result schema, FESA HDF5 to Reference CSV comparison schema를 정의해야 한다.
|
||||
|
||||
## I/O Definition Agent 역할
|
||||
|
||||
I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, output request mapping, HDF5 result schema, reference CSV comparison row schema를 정의한다.
|
||||
|
||||
수행한다:
|
||||
- 기능별 supported Abaqus keyword subset을 정의한다.
|
||||
- unsupported, ignored-with-warning, requires-user-decision keyword 정책을 정의한다.
|
||||
- model data와 history data를 내부 solver 개념으로 매핑한다.
|
||||
- node, element, set, material, section, boundary condition, load, step, output request의 의미 계약을 정의한다.
|
||||
- `results.h5`의 authoritative HDF5 schema를 정의한다.
|
||||
- 기능이 선언한 existing Abaqus CSV와 비교하기 위한 최소 source-ID/component mapping을 정의한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- parser를 구현하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- solver 결과와 reference 결과를 비교하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- 명시적으로 정의되지 않은 Abaqus full compatibility를 주장하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> I/O Definition
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
|
||||
- source_research: docs/research/<feature-id>-research.md
|
||||
- status: draft | needs-user-decision | ready-for-implementation-planning
|
||||
- owner_agent: io-definition-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Abaqus Input Scope
|
||||
- input_format: Abaqus input file (`.inp`)
|
||||
- abaqus_documentation_source: <version/source URL>
|
||||
- compatibility_disclaimer: FESA supports only the keyword subset defined in this document.
|
||||
|
||||
| keyword | support_status | level | required_parameters | mapped_internal_concept | notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| *HEADING | supported | model | N/A | model title | optional |
|
||||
| *INCLUDE | supported | model/history | INPUT | include file | path policy required |
|
||||
| *NODE | supported | model | N/A | node label and coordinates | |
|
||||
| *NSET | supported | model | NSET | node set | sorted/unsorted policy required |
|
||||
| *ELEMENT | supported | model | TYPE | element label, type, connectivity | |
|
||||
| *ELSET | supported | model | ELSET | element set | |
|
||||
| *MATERIAL | supported | model | NAME | material | |
|
||||
| *ELASTIC | supported | model | N/A or TYPE | elastic material data | |
|
||||
| <section keyword> | supported | model | ELSET, MATERIAL | section assignment | e.g. *SOLID SECTION |
|
||||
| *BOUNDARY | supported | model/history | N/A | boundary condition | |
|
||||
| *CLOAD | supported | history | N/A | concentrated load | feature-dependent |
|
||||
| *DLOAD | supported | history | N/A | distributed load | feature-dependent |
|
||||
| *STEP | supported | history | N/A | analysis step | |
|
||||
| <procedure keyword> | supported | history | N/A | analysis procedure | e.g. *STATIC |
|
||||
| *OUTPUT | supported | history | N/A | output request root | |
|
||||
| *NODE OUTPUT | supported | history | N/A | nodal output request | |
|
||||
| *ELEMENT OUTPUT | supported | history | N/A | element output request | |
|
||||
|
||||
## Syntax Policy
|
||||
- case_insensitivity: <policy>
|
||||
- comma_separated_fields: <policy>
|
||||
- comment_lines: lines beginning with `**`
|
||||
- keyword_continuation: <policy>
|
||||
- include_files: <relative path policy>
|
||||
- labels: <case/quote/name policy>
|
||||
- line_length_limit: <policy>
|
||||
- ascii_assumption: <policy>
|
||||
- empty_data_fields: <policy>
|
||||
|
||||
## Model Data Mapping
|
||||
- nodes: <node label, coordinate dimension, coordinate system>
|
||||
- elements: <element label, element type, connectivity>
|
||||
- node_sets: <set name, sorted/unsorted, expansion rules>
|
||||
- element_sets: <set name, expansion rules>
|
||||
- material: <material name and data>
|
||||
- section: <section assignment>
|
||||
- coordinates: <global/local coordinate conventions>
|
||||
- units: <unit system policy>
|
||||
|
||||
## History Data Mapping
|
||||
- steps: <step naming and order>
|
||||
- procedure: <analysis procedure keyword mapping>
|
||||
- boundary_conditions: <boundary condition mapping>
|
||||
- loads: <load keyword mapping>
|
||||
- output_requests: <node/element output mapping>
|
||||
|
||||
## Internal Model Contract
|
||||
- node_label: <semantic contract>
|
||||
- element_label: <semantic contract>
|
||||
- element_type: <semantic contract>
|
||||
- connectivity: <semantic contract>
|
||||
- set_membership: <semantic contract>
|
||||
- material: <semantic contract>
|
||||
- section: <semantic contract>
|
||||
- boundary_condition: <semantic contract>
|
||||
- load: <semantic contract>
|
||||
- step: <semantic contract>
|
||||
- output_request: <semantic contract>
|
||||
|
||||
## Output HDF5 Schema
|
||||
|
||||
- authoritative_file: `results.h5`
|
||||
- schema_version: <version>
|
||||
- root_attributes: units, coordinate_system, solver_version, feature_id, model_id
|
||||
- step_frame_identity: <step/frame naming and ordering>
|
||||
- row_identity_policy: <node_id | element_id | integration_point | component mapping>
|
||||
|
||||
| quantity | dataset_path | shape | dtype | required_attributes | location | notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| displacement | /steps/<step>/frames/<frame>/field_outputs/U | <nnode, ndim> | float64 | component_names, units | nodal | |
|
||||
| reaction | /steps/<step>/frames/<frame>/field_outputs/RF | <nnode, ndim> | float64 | component_names, units | nodal | |
|
||||
| element_force | /steps/<step>/frames/<frame>/field_outputs/element_forces | <nrow, ncomp> | float64 | component_names, element_ids, location | element | feature-dependent |
|
||||
| stress | /steps/<step>/frames/<frame>/field_outputs/S | <nrow, ncomp> | float64 | component_names, element_ids, integration_points | integration_point | feature-dependent |
|
||||
|
||||
## FESA HDF5 to Reference CSV Comparison Mapping
|
||||
|
||||
FESA solver output은 `results.h5`이다. 기능이 blocking 또는 warning-only로 선언한
|
||||
quantity에 대해서만 existing CSV path와 다음 mapping을 정의한다.
|
||||
|
||||
| field | contract |
|
||||
| --- | --- |
|
||||
| reference_input | exact existing `.inp` path |
|
||||
| reference_csv | exact existing required CSV path |
|
||||
| hdf5_dataset | authoritative FESA dataset path |
|
||||
| source_identity | node/element source label used for exact matching |
|
||||
| components | required CSV columns and corresponding HDF5 components |
|
||||
| row_precheck | missing/extra/duplicate/nonfinite required rows fail before tolerance |
|
||||
| behavior | blocking or warning-only |
|
||||
| tolerance | upstream-approved formula |
|
||||
|
||||
Row order alone으로 대응하지 않는다. Canonical filename, reference CSV schema version,
|
||||
README, metadata, provenance 또는 single-step/final-frame case의 duplicated unit/coordinate/
|
||||
step-frame columns를 요구하지 않는다.
|
||||
|
||||
## Validation Rules
|
||||
- required_fields: <required input fields>
|
||||
- duplicate_labels: <policy>
|
||||
- missing_references: <policy>
|
||||
- unsupported_keywords: unsupported | ignored-with-warning | requires-user-decision
|
||||
- set_expansion: <policy>
|
||||
- coordinate_conventions: <policy>
|
||||
- output_quantity_availability: <policy>
|
||||
- hdf5_schema_validation: <required datasets and attributes>
|
||||
- reference_csv_validation: <stable ordering and required columns>
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
|
||||
### Reference Model Agent
|
||||
- <Abaqus input examples and reference artifact schema needs>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <parser acceptance cases, unsupported keyword diagnostics, HDF5 writer tests, comparison row mapping tests>
|
||||
|
||||
### Reference Verification Agent
|
||||
- <HDF5 dataset paths, reference CSV row schemas, ID matching rules, units, coordinate conventions, tolerance-relevant fields>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 입력 파일은 Abaqus `.inp`임을 명시해야 한다.
|
||||
- Abaqus full compatibility를 주장하지 않고 기능별 supported keyword subset을 명시해야 한다.
|
||||
- model data와 history data의 매핑을 구분해야 한다.
|
||||
- unsupported keyword 처리 정책을 명확히 해야 한다.
|
||||
- 내부 모델 계약은 semantic fields로 작성하고 C++ class/function/API를 확정하지 않는다.
|
||||
- `results.h5`가 authoritative solver output임을 명시해야 한다.
|
||||
- HDF5 schema는 dataset path, dtype/shape, required attributes, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.
|
||||
- Reference CSV comparison mapping은 exact path, source-ID column, required component columns,
|
||||
HDF5 projection, row prechecks와 tolerance를 포함해야 한다.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Linear Static 3D Euler Beam Coordination Report
|
||||
|
||||
## Metadata
|
||||
|
||||
- feature_id: linear-static-3d-euler-beam
|
||||
- status: completed
|
||||
- owner_agent: coordinator-agent
|
||||
- date: 2026-08-15
|
||||
- migration_note: Existing evidence was relocated without rerunning workflow gates.
|
||||
|
||||
## Worklist
|
||||
|
||||
| stage | owner | status | evidence |
|
||||
| --- | --- | --- | --- |
|
||||
| 1. requirements | requirement-agent | passed | `requirements.md` |
|
||||
| 2. research | research-agent | passed | `research.md` |
|
||||
| 3. formulation | formulation-agent | passed | `formulation.md` |
|
||||
| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` |
|
||||
| 5. I/O | io-definition-agent | passed | `io.md` |
|
||||
| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `implementation-report.md`; `build-test.md`; `reference-comparison.md` |
|
||||
| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` |
|
||||
| 8. release | release-agent | passed | `release.md` |
|
||||
|
||||
## Current Progress
|
||||
|
||||
- active_sub_agent: none
|
||||
- next_handoff: none
|
||||
- closure_evidence: `release.md` status `ready-for-release`
|
||||
- workflow_disposition: completed
|
||||
|
||||
## Decision Log
|
||||
|
||||
| date | decision | evidence | rationale |
|
||||
| --- | --- | --- | --- |
|
||||
| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. |
|
||||
|
||||
## Blockers and Rework
|
||||
|
||||
- active_blockers: none
|
||||
- correction_attempt_count: 0
|
||||
- needs_user_decision: false
|
||||
@@ -0,0 +1,42 @@
|
||||
# Linear Static MITC4 Shell Coordination Report
|
||||
|
||||
## Metadata
|
||||
|
||||
- feature_id: linear-static-mitc4-shell
|
||||
- status: completed
|
||||
- owner_agent: coordinator-agent
|
||||
- date: 2026-08-15
|
||||
- migration_note: Existing evidence was relocated without rerunning workflow gates.
|
||||
|
||||
## Worklist
|
||||
|
||||
| stage | owner | status | evidence |
|
||||
| --- | --- | --- | --- |
|
||||
| 1. requirements | requirement-agent | passed | `requirements.md` |
|
||||
| 2. research | research-agent | passed | `research.md` |
|
||||
| 3. formulation | formulation-agent | passed | `formulation.md` |
|
||||
| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` |
|
||||
| 5. I/O | io-definition-agent | passed | `io.md` |
|
||||
| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `build-test.md`; `reference-comparison.md` |
|
||||
| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` |
|
||||
| 8. release | release-agent | passed | `release.md` |
|
||||
|
||||
## Current Progress
|
||||
|
||||
- active_sub_agent: none
|
||||
- next_handoff: none
|
||||
- closure_evidence: `release.md` status `ready-for-release`
|
||||
- workflow_disposition: completed
|
||||
- historical_gap: No standalone `implementation-report.md` existed before migration; no replacement was fabricated.
|
||||
|
||||
## Decision Log
|
||||
|
||||
| date | decision | evidence | rationale |
|
||||
| --- | --- | --- | --- |
|
||||
| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. |
|
||||
|
||||
## Blockers and Rework
|
||||
|
||||
- active_blockers: none
|
||||
- correction_attempt_count: 0
|
||||
- needs_user_decision: false
|
||||
@@ -1,104 +0,0 @@
|
||||
# 수치 검토 리포트 작성 가이드
|
||||
|
||||
이 디렉터리는 Numerical Review Agent가 작성하거나 제안한 기능별 수치 검토 리포트를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/numerical-reviews/<feature-id>-review.md` 형식을 사용한다. 각 리포트는 Formulation Agent의 정식화 문서를 독립 검토해, 구현 계획 단계로 넘겨도 되는지 판단한다.
|
||||
|
||||
## Numerical Review Agent 역할
|
||||
|
||||
Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위험, 검증 준비 상태를 검토한다.
|
||||
|
||||
수행한다:
|
||||
- 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
|
||||
- `B` matrix 또는 kinematic operator, constitutive contract, element equation을 검토한다.
|
||||
- rigid body modes, patch test, symmetry, positive definiteness를 확인한다.
|
||||
- hourglass, shear locking, volumetric locking, distortion, singular Jacobian, conditioning 위험을 식별한다.
|
||||
- 구현 계획 전에 필요한 정식화 수정, 연구 보강, reference model 요구사항을 작성한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 정식화 문서를 직접 수정하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- 레퍼런스 결과와 구현 솔버 결과의 일치 여부를 판정하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Numerical Review
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- status: pass-for-implementation-planning | needs-formulation-revision | needs-research | blocked
|
||||
- owner_agent: numerical-review-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Review Verdict
|
||||
- verdict: pass-for-implementation-planning | needs-formulation-revision | needs-research | blocked
|
||||
- reason: <판정 이유>
|
||||
|
||||
## Critical Findings
|
||||
- <구현 전 반드시 수정할 수식 또는 수치 결함>
|
||||
|
||||
## Numerical Risk Assessment
|
||||
- rigid_body_modes: <check/risk>
|
||||
- patch_test: <check/risk>
|
||||
- symmetry: <check/risk>
|
||||
- positive_definiteness: <check/risk>
|
||||
- hourglass: <check/risk or N/A>
|
||||
- shear_locking: <check/risk or N/A>
|
||||
- volumetric_locking: <check/risk or N/A>
|
||||
- distortion: <check/risk>
|
||||
- singular_jacobian: <check/risk>
|
||||
- conditioning: <check/risk>
|
||||
- convergence: <check/risk or N/A>
|
||||
|
||||
## Consistency Checks
|
||||
- units: <pass/fail/TBD>
|
||||
- dimensions: <pass/fail/TBD>
|
||||
- signs: <pass/fail/TBD>
|
||||
- dof_ordering: <pass/fail/TBD>
|
||||
- coordinate_transforms: <pass/fail/TBD>
|
||||
- matrix_vector_dimensions: <pass/fail/TBD>
|
||||
- integration_weights: <pass/fail/TBD>
|
||||
- output_locations: <pass/fail/TBD>
|
||||
|
||||
## Verification Readiness
|
||||
- unit_tests: <필요한 단위 테스트>
|
||||
- patch_tests: <필요한 patch test>
|
||||
- mms_or_mes: <MMS/MES 후보 또는 N/A>
|
||||
- benchmark_reference_comparison: <필요한 benchmark/reference 비교>
|
||||
- missing_evidence: <누락된 검증 근거>
|
||||
|
||||
## Required Revisions
|
||||
|
||||
### Formulation Agent
|
||||
- <정식화 수정 지시>
|
||||
|
||||
### Research Agent
|
||||
- <연구 보강 지시>
|
||||
|
||||
### Reference Model Agent
|
||||
- <optional downstream test note; not a formulation blocker>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <테스트와 acceptance criteria로 변환할 항목>
|
||||
|
||||
### Reference Model Agent
|
||||
- <테스트 모델로 변환할 항목>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 확인된 결함, 위험, open question을 구분해야 한다.
|
||||
- `pass-for-implementation-planning`은 구현 계획으로 넘겨도 된다는 뜻이며 기능 완료나 release 승인이 아니다.
|
||||
- 정식화 문서를 직접 수정하지 않고 필요한 수정을 명확히 지시해야 한다.
|
||||
- 모든 검토는 dimension, sign, DOF ordering, coordinate transform, Jacobian, integration weight, element equation, output recovery를 포함해야 한다.
|
||||
- numerical risk는 approved feature scope가 요구하는 항목만 포함한다. 이후 Reference Model
|
||||
문서, canonical naming, README, metadata, provenance, expanded portfolio 또는 아직 없는
|
||||
comparison result는 formulation verdict의 blocker가 아니다.
|
||||
@@ -1,170 +0,0 @@
|
||||
# Physics Evaluation Report 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Physics Evaluation Agent가 작성하거나 제안하는 기능별 physics evaluation report를 보관하는 위치다.
|
||||
|
||||
Physics Evaluation Agent는 Reference Verification Agent가 `pass-for-physics-evaluation`로 넘긴 결과에 대해 물리적 타당성을 검토한다. 이 agent는 reference tolerance를 다시 판정하지 않고, FESA `results.h5`, Abaqus reference CSV files, optional FESA debug CSV view를 읽기 전용 evidence로 사용해 평형, 반력 부호, 변위 방향, 대칭성, 요소내력/응력 위치, rigid body mode 징후, energy/residual sanity, 테스트 모델 coverage를 검토한다.
|
||||
|
||||
기본 문서명은 `docs/physics-evaluations/<feature-id>-physics-evaluation.md` 형식을 사용한다.
|
||||
|
||||
## Physics Evaluation Agent 역할
|
||||
|
||||
수행한다:
|
||||
- Reference Verification report가 `pass-for-physics-evaluation`인지 확인한다.
|
||||
- documented physical expectation이 있는 항목만 pass/fail로 판정한다.
|
||||
- global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, energy/residual, model coverage를 검토한다.
|
||||
- 물리 검토 실패를 equilibrium-failure, reaction-inconsistency, displacement-direction-failure, symmetry-failure, stress-location-failure, element-force-inconsistency, rigid-body-mode-suspected, nonfinite-result, model-coverage-gap, upstream-contract, environment로 분류한다.
|
||||
- 실패 원인에 따라 Correction Agent, Reference Model Agent, Formulation Agent, I/O Definition Agent, Coordinator Agent로 handoff한다.
|
||||
- 모든 물리 검토가 문서화된 기대값을 만족하면 Release Agent로 handoff한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- source code를 수정하지 않는다.
|
||||
- tests를 수정하지 않는다.
|
||||
- CMake files를 수정하지 않는다.
|
||||
- requirements, formulations, I/O contracts, reference model contracts를 수정하지 않는다.
|
||||
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
|
||||
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- reference tolerance를 다시 판정하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- release notes 또는 final release checklist를 작성하지 않는다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
Physics Evaluation Agent는 다음 순서를 따른다.
|
||||
|
||||
```text
|
||||
EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
|
||||
```
|
||||
|
||||
`EVIDENCE CHECK`에서 다음 항목을 확인한다.
|
||||
|
||||
- Reference Verification report status가 `pass-for-physics-evaluation`인지 여부
|
||||
- checked solver HDF5 file: `<solver output directory>/results.h5`
|
||||
- checked feature-declared Abaqus reference CSV files
|
||||
- optional FESA deterministic CSV view derived from `results.h5` for review only
|
||||
- compared quantities
|
||||
- model purpose
|
||||
- documented physical expectations
|
||||
- sign convention
|
||||
- units and coordinate system
|
||||
- output location and component naming
|
||||
|
||||
## Physics Checks
|
||||
|
||||
- `global equilibrium`: 적용 하중, 반력, sign convention이 문서화된 경우 전체 힘/모멘트 평형을 검토한다.
|
||||
- `reaction consistency`: constrained DOF와 reaction component가 경계조건과 일관적인지 검토한다.
|
||||
- `displacement direction`: 하중 방향, 구속조건, 예상 변형 모드와 변위 부호/방향이 맞는지 검토한다.
|
||||
- `symmetry`: symmetry, antisymmetry, expected zero component가 모델 목적과 일치하는지 검토한다.
|
||||
- `element force balance`: element internal force가 외력/반력 균형 또는 부호 일관성을 만족하는지 검토한다.
|
||||
- `stress/strain`: stress/strain 부호, component, coordinate system, output location이 모델 expectation과 일치하는지 검토한다.
|
||||
- `rigid body mode`: 불완전 구속, 비정상적으로 큰 변위, near-zero stiffness 징후를 검토한다.
|
||||
- `energy/residual`: `csv/energy_or_residual.csv` 또는 residual output이 있을 때 energy balance, residual trend, convergence sanity를 검토한다.
|
||||
- `model coverage`: reference model이 claimed feature를 충분히 검증하는지 검토한다.
|
||||
|
||||
## Failure Classification
|
||||
|
||||
- `equilibrium-failure`: 전체 하중-반력 또는 모멘트 평형이 기대와 다르다.
|
||||
- `reaction-inconsistency`: constrained DOF reaction이 boundary condition 또는 load path와 일관되지 않는다.
|
||||
- `displacement-direction-failure`: 변위 방향 또는 부호가 하중/구속조건과 물리적으로 맞지 않는다.
|
||||
- `symmetry-failure`: expected symmetry, antisymmetry, zero component가 깨졌다.
|
||||
- `stress-location-failure`: stress/strain output location 또는 component 해석이 물리 expectation과 맞지 않는다.
|
||||
- `element-force-inconsistency`: element internal force balance 또는 sign이 일관되지 않는다.
|
||||
- `rigid-body-mode-suspected`: rigid body mode 또는 under-constrained model 징후가 있다.
|
||||
- `nonfinite-result`: NaN 또는 infinite value가 있다.
|
||||
- `model-coverage-gap`: reference model이 기능을 충분히 검증하지 못한다.
|
||||
- `upstream-contract`: physical expectation, sign convention, unit, coordinate, output location 계약이 누락 또는 충돌한다.
|
||||
- `environment`: 로컬 실행/읽기 환경 문제로 평가가 불가능하다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Physics Evaluation Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_reference_verification_report: docs/reference-verifications/<feature-id>-reference-verification.md
|
||||
- source_reference_model: docs/reference-models/<feature-id>-reference-models.md
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- status: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
|
||||
- owner_agent: physics-evaluation-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Input Evidence
|
||||
|
||||
| evidence | path_or_source | status | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <summary> |
|
||||
| solver_hdf5 | <solver output directory>/results.h5 | present | missing | <summary> |
|
||||
| solver_csv_views | <solver output directory>/csv/ | present | missing | <summary or N/A> |
|
||||
| declared_reference_csv | <exact feature-declared path> | present | missing | <blocking/warning quantity summary> |
|
||||
| model_purpose | docs/reference-models/<feature-id>-reference-models.md | documented | missing | <summary> |
|
||||
| physical_expectations | <source docs> | documented | missing | <summary> |
|
||||
|
||||
## Physics Checks
|
||||
|
||||
| check | documented_expectation | observed_evidence | verdict | classification |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| global equilibrium | <expected force/moment balance> | <observed> | pass | fail | skipped | equilibrium-failure |
|
||||
| reaction consistency | <expected reaction behavior> | <observed> | pass | fail | skipped | reaction-inconsistency |
|
||||
| displacement direction | <expected direction/sign> | <observed> | pass | fail | skipped | displacement-direction-failure |
|
||||
| symmetry | <expected symmetry/zero components> | <observed> | pass | fail | skipped | symmetry-failure |
|
||||
| element force balance | <expected element force relation> | <observed> | pass | fail | skipped | element-force-inconsistency |
|
||||
| stress/strain sanity | <expected sign/location/component> | <observed> | pass | fail | skipped | stress-location-failure |
|
||||
| rigid body mode | <expected constrained behavior> | <observed> | pass | fail | skipped | rigid-body-mode-suspected |
|
||||
| energy/residual | <expected energy/residual sanity> | <observed> | pass | fail | skipped | upstream-contract |
|
||||
| model coverage | <claimed feature coverage> | <observed> | pass | fail | skipped | model-coverage-gap |
|
||||
|
||||
## Failure Classification
|
||||
- classification: equilibrium-failure | reaction-inconsistency | displacement-direction-failure | symmetry-failure | stress-location-failure | element-force-inconsistency | rigid-body-mode-suspected | nonfinite-result | model-coverage-gap | upstream-contract | environment | N/A
|
||||
- primary_failure: <short summary>
|
||||
- evidence: <short relevant evidence>
|
||||
|
||||
## Evaluation Verdict
|
||||
- verdict: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
|
||||
- reason: <short reason>
|
||||
|
||||
## Handoff Recommendation
|
||||
|
||||
| target_agent | reason | required_input |
|
||||
| --- | --- | --- |
|
||||
| Correction Agent | <implementation-owned physical failure> | <failed check and evidence> |
|
||||
| Reference Model Agent | <model coverage or missing physical expectation issue> | <coverage gap> |
|
||||
| Formulation Agent | <formulation or sign convention issue> | <failed physics check> |
|
||||
| I/O Definition Agent | <output location/component/unit/coordinate ambiguity> | <contract gap> |
|
||||
| Coordinator Agent | <blocked or repeated ambiguity> | <classification and open issue> |
|
||||
| Release Agent | <all documented physics checks passed> | <evaluation report> |
|
||||
|
||||
## 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
|
||||
- <missing physical expectation, incomplete model coverage, contradictory sign convention, or unavailable energy/residual evidence>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
|
||||
- `pass-for-release-agent`: documented physics checks가 통과했고 Release Agent가 release readiness를 평가할 수 있다.
|
||||
- `needs-correction`: implementation-owned physical failure가 있어 Correction Agent가 필요하다.
|
||||
- `needs-reference-model`: feature-required case 또는 명시적으로 요구된 physical expectation이 누락됐다.
|
||||
- `needs-formulation-review`: formulation 또는 numerical review 재검토가 필요하다.
|
||||
- `needs-io-decision`: output location, component naming, sign convention, unit, coordinate mapping이 evaluation을 막는다.
|
||||
- `needs-upstream-decision`: physical expectation, sign convention, model purpose, acceptance criterion이 누락 또는 충돌한다.
|
||||
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- Reference Verification report가 `pass-for-physics-evaluation`이 아니면 physics pass를 판정하지 않는다.
|
||||
- documented expectation이 없는 항목은 `skipped`로 두며 expanded portfolio나 calibration을
|
||||
새 gate로 만들지 않는다. Feature-required expectation 자체가 누락된 경우에만
|
||||
`needs-upstream-decision` 또는 `needs-reference-model`을 사용한다.
|
||||
- 평형 검토는 적용 하중, 반력, element/internal force sign convention이 문서화된 경우에만 수행한다.
|
||||
- stress/strain 검토는 output location, component naming, coordinate system, units가 정의된 경우에만 수행한다.
|
||||
- FESA `results.h5`, Abaqus reference CSV files, optional FESA debug CSV view는 읽기 전용 evidence로만 사용한다.
|
||||
- pass는 Release Agent로 넘길 수 있다는 뜻이며 release readiness 승인이 아니다.
|
||||
- reference artifacts와 tolerance policies는 수정하지 않는다.
|
||||
@@ -1,91 +0,0 @@
|
||||
# Reference Case 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Reference Model Agent가 작성하는 기능별 lightweight reference-case
|
||||
inventory를 보관한다. Abaqus는 외부 수치 reference이며 FESA의 formulation 또는 내부
|
||||
동작 계약이 아니다.
|
||||
|
||||
기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md`다. Agent는 Abaqus
|
||||
또는 다른 reference solver를 실행하지 않고 `reference/` 파일을 생성, 수정, rename,
|
||||
repair 또는 normalize하지 않는다.
|
||||
|
||||
## 필수 내용
|
||||
|
||||
기능이 실제로 비교하는 case마다 다음만 기록한다.
|
||||
|
||||
- case id와 목적
|
||||
- existing `.inp` exact path
|
||||
- blocking 또는 warning-only quantity의 existing CSV exact path
|
||||
- FESA HDF5 dataset
|
||||
- source identity와 component mapping
|
||||
- missing/extra/duplicate/nonfinite row precheck
|
||||
- approved tolerance
|
||||
- artifact presence/readability status
|
||||
|
||||
다음은 기본 readiness 조건이 아니다.
|
||||
|
||||
- canonical directory/file naming 또는 legacy-alias 승인
|
||||
- bundle `README.md` 또는 `metadata.json`
|
||||
- Abaqus version/generation provenance
|
||||
- duplicated units, coordinates, model, step/frame, material, section, thickness, element type
|
||||
- reference CSV schema version
|
||||
- 비교하지 않는 quantity CSV
|
||||
- 요구조건이 요청하지 않은 benchmark portfolio
|
||||
|
||||
단일 static step/final frame 기능은 input/CSV pair로 result state를 식별한다. Material,
|
||||
section, loads, constraints와 source element type은 `.inp`에서 읽는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <Feature Title> Reference Cases
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- status: draft | needs-user-decision | needs-reference-artifacts | ready-for-implementation-planning | blocked
|
||||
- owner_agent: reference-model-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Reference Acceptance Scope
|
||||
- blocking_quantities: [<quantity/components>]
|
||||
- warning_only_quantities: [<quantity/components>]
|
||||
- excluded_quantities: [<quantity/reason>]
|
||||
|
||||
## Reference Case Inventory
|
||||
|
||||
| case_id | purpose | input | required_csv | quantity | behavior | status |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| <case> | <purpose> | reference/<dir>/<file>.inp | reference/<dir>/<file>.csv | <components> | blocking | warning-only | present | missing |
|
||||
|
||||
## HDF5-to-CSV Comparison Mapping
|
||||
|
||||
| case_id | hdf5_dataset | source_id | csv_id_column | components | row_precheck |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| <case> | <path> | <node/element source id> | <column> | <components> | exact set; unique; finite |
|
||||
|
||||
## Tolerance and Blocking/Warning Policy
|
||||
- reference_scale: <formula>
|
||||
- row_tolerance: <formula>
|
||||
- zero_policy: no clamp
|
||||
- blocking_behavior: <rule>
|
||||
- warning_behavior: <rule>
|
||||
|
||||
## Readiness Checklist
|
||||
- declared input exists and is readable
|
||||
- every required CSV exists and is readable
|
||||
- source identity and required components are deterministic
|
||||
- row-set/nonfinite prechecks are defined
|
||||
- tolerance and blocking/warning behavior are approved
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
- <only missing required files, matching, tolerance, or feature-owned decisions>
|
||||
```
|
||||
|
||||
## 상태 규칙
|
||||
|
||||
- `ready-for-implementation-planning`: required input/CSV files, mapping, and tolerance are complete.
|
||||
- `needs-reference-artifacts`: a declared input or required comparison CSV is missing.
|
||||
- `needs-user-decision`: required quantity, mapping, or tolerance is undefined.
|
||||
- `blocked`: no safe progress is possible without an external decision or state change.
|
||||
|
||||
Canonical naming, README, metadata, provenance, and unrequested portfolio coverage do not select
|
||||
any failure status.
|
||||
@@ -1,107 +0,0 @@
|
||||
# Reference Verification Report 작성 가이드
|
||||
|
||||
Reference Verification Agent는 Build/Test 통과 뒤 FESA `results.h5`와 기능이 선언한
|
||||
Abaqus CSV quantity를 비교한다. 비교 대상은 observable value이며 Abaqus 내부 formulation
|
||||
동등성이 아니다.
|
||||
|
||||
기본 문서명은 `docs/reference-verifications/<feature-id>-reference-verification.md`다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
```text
|
||||
ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
```
|
||||
|
||||
`ARTIFACT CHECK`는 다음만 요구한다.
|
||||
|
||||
- declared `.inp`
|
||||
- generated FESA `results.h5`
|
||||
- every feature-required Abaqus CSV
|
||||
- HDF5 dataset projection
|
||||
- source-ID/component mapping
|
||||
- blocking/warning behavior
|
||||
- approved tolerance
|
||||
|
||||
Canonical naming, README, metadata, Abaqus version/provenance, duplicated units/coordinates/
|
||||
step-frame fields와 reference CSV schema version은 기본 gate가 아니다.
|
||||
|
||||
Missing, extra, duplicate 또는 nonfinite required row는 tolerance 전에 실패한다. Row order
|
||||
alone으로 대응하지 않는다. FESA/Reference 값을 zero-clamp하거나 tolerance에 맞게 보정하지
|
||||
않는다.
|
||||
|
||||
## 보고 항목
|
||||
|
||||
각 blocking 또는 warning-only quantity에 대해 다음을 보고한다.
|
||||
|
||||
- exact input and CSV path
|
||||
- FESA HDF5 dataset
|
||||
- source ID/component mapping
|
||||
- compared, missing, extra, duplicate, nonfinite row counts
|
||||
- max absolute and relative error
|
||||
- RMS and norm error when required
|
||||
- worst source ID/component
|
||||
- pass, fail, or warning
|
||||
|
||||
## Failure Classification
|
||||
|
||||
- `missing-reference-artifact`: declared input or required CSV missing
|
||||
- `missing-solver-output`: `results.h5` or comparison command missing
|
||||
- `schema-mismatch`: required source ID/component columns unavailable
|
||||
- `id-mismatch`: required source row sets do not match
|
||||
- `tolerance-failure`: blocking value exceeds approved tolerance
|
||||
- `nonfinite-result`: required FESA or reference value is not finite
|
||||
- `upstream-contract`: quantity, HDF5 projection, mapping, or tolerance missing/contradictory
|
||||
- `environment`: local comparison cannot run
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <Feature Title> Reference Verification Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- status: pass-for-physics-evaluation | needs-correction | needs-reference-artifacts | needs-solver-results | needs-upstream-decision | blocked
|
||||
- owner_agent: reference-verification-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Artifact Inventory
|
||||
| item | path | status | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| input | <exact path> | present | missing | <summary> |
|
||||
| required_csv | <exact path> | present | missing | <summary> |
|
||||
| solver_hdf5 | <path>/results.h5 | present | missing | <summary> |
|
||||
|
||||
## Comparison Contract
|
||||
- hdf5_dataset: <path>
|
||||
- source_id_mapping: <rule>
|
||||
- components: <blocking/warning inventory>
|
||||
- row_precheck: exact set; unique; finite
|
||||
- tolerance_source: <path/requirement>
|
||||
- tolerance_policy: <formula>
|
||||
|
||||
## Quantity Results
|
||||
| quantity | components | behavior | compared | missing | extra | max_abs | max_rel | rms | norm | worst_id/component | result |
|
||||
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |
|
||||
| <quantity> | <components> | blocking | warning-only | <values> |
|
||||
|
||||
## Failure Classification
|
||||
- classification: <value or N/A>
|
||||
- evidence: <summary>
|
||||
|
||||
## Handoff Recommendation
|
||||
- <target and exact evidence>
|
||||
|
||||
## No-Change Assertion
|
||||
- source_files_modified: false
|
||||
- test_files_modified: false
|
||||
- cmake_files_modified: false
|
||||
- reference_artifacts_modified: false
|
||||
- tolerance_policies_modified: false
|
||||
|
||||
## Open Issues
|
||||
- <only actual comparison blockers>
|
||||
```
|
||||
|
||||
`pass-for-physics-evaluation`은 required blocking comparison 통과만 의미한다. Warning-only
|
||||
quantity는 경고를 남기되 verdict를 바꾸지 않는다. Physics validation과 release readiness는
|
||||
각 후속 agent가 판정한다.
|
||||
@@ -1,173 +0,0 @@
|
||||
# Release Report 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Release Agent가 작성하거나 제안하는 기능별 release readiness report를 보관하는 위치다.
|
||||
|
||||
Release Agent는 Physics Evaluation Agent가 `pass-for-release-agent`로 넘긴 기능에 대해 최종 gate evidence를 감사한다. 이 Agent는 source code, tests, CMake, upstream 계약, reference artifacts, tolerance policies를 수정하지 않는다. 또한 Abaqus/Nastran 실행, Abaqus reference CSV 생성 또는 수정, 외부 publish/deploy/package/tag/commit 작업을 수행하지 않는다.
|
||||
|
||||
기본 문서명은 `docs/releases/<feature-id>-release.md` 형식을 사용한다.
|
||||
|
||||
## Release Agent 역할
|
||||
|
||||
수행한다:
|
||||
- upstream gate report가 같은 `feature_id`를 대상으로 하는지 확인한다.
|
||||
- Build/Test report의 `pass-for-reference-verification` 상태를 확인한다.
|
||||
- Reference Verification report의 `pass-for-physics-evaluation` 상태를 확인한다.
|
||||
- Physics Evaluation report의 `pass-for-release-agent` 상태를 확인한다.
|
||||
- 모든 `must` requirement가 acceptance criterion, test/reference evidence, release scope에 trace되는지 확인한다.
|
||||
- known limitations, deferred issues, unsupported Abaqus keyword, accepted risks를 release note에 기록한다.
|
||||
- release checklist와 Release Notes Draft를 작성한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- source code를 수정하지 않는다.
|
||||
- tests를 수정하지 않는다.
|
||||
- CMake files 또는 build configuration을 수정하지 않는다.
|
||||
- requirements, formulations, I/O contracts, numerical review reports, reference verification reports, physics evaluation reports를 수정하지 않는다.
|
||||
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
|
||||
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- 실패하거나 누락된 upstream gate를 우회하지 않는다.
|
||||
- 사용자 명시 요청 없이 publish, deploy, package, tag, commit, external release를 수행하지 않는다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
Release Agent는 다음 순서를 따른다.
|
||||
|
||||
```text
|
||||
GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
|
||||
```
|
||||
|
||||
`GATE AUDIT`에서는 다음 evidence를 확인한다.
|
||||
|
||||
- Physics Evaluation report status: `pass-for-release-agent`
|
||||
- Reference Verification report status: `pass-for-physics-evaluation`
|
||||
- Build/Test report status: `pass-for-reference-verification`
|
||||
- Implementation report와 implementation plan의 feature scope 일치
|
||||
- requirements, formulations, numerical reviews, I/O definitions, reference models 문서의 feature scope 일치
|
||||
- Build/Test report의 `.harness/config.json` 또는 자동 감지 기반 MSVC build/test command evidence
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Release Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
|
||||
- source_io_definition: docs/io-definitions/<feature-id>-io.md
|
||||
- source_reference_model: docs/reference-models/<feature-id>-reference-models.md
|
||||
- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
|
||||
- source_build_test_report: docs/build-test-reports/<feature-id>-build-test.md
|
||||
- source_reference_verification_report: docs/reference-verifications/<feature-id>-reference-verification.md
|
||||
- source_physics_evaluation_report: docs/physics-evaluations/<feature-id>-physics-evaluation.md
|
||||
- status: ready-for-release | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-documentation | needs-upstream-decision | blocked
|
||||
- owner_agent: release-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Release Scope
|
||||
|
||||
| item | included | excluded | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| analysis_type | <supported analysis> | <unsupported analysis> | <notes> |
|
||||
| element_type | <supported elements> | <unsupported elements> | <notes> |
|
||||
| material_model | <supported materials> | <unsupported materials> | <notes> |
|
||||
| Abaqus input subset | <supported keywords> | <unsupported keywords> | <notes> |
|
||||
| output_quantities | <supported outputs> | <unsupported outputs> | <notes> |
|
||||
|
||||
## Gate Evidence Inventory
|
||||
|
||||
| gate | source | expected_status | observed_status | verdict |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| requirements | docs/requirements/<feature-id>.md | approved or release-ready | <status> | pass | fail | missing |
|
||||
| formulation | docs/formulations/<feature-id>-formulation.md | reviewed | <status> | pass | fail | missing |
|
||||
| numerical_review | docs/numerical-reviews/<feature-id>-review.md | pass-for-implementation-planning | <status> | pass | fail | missing |
|
||||
| io_definition | docs/io-definitions/<feature-id>-io.md | ready | <status> | pass | fail | missing |
|
||||
| reference_model | docs/reference-models/<feature-id>-reference-models.md | ready or artifacts present | <status> | pass | fail | missing |
|
||||
| implementation | <implementation report> | implemented | <status> | pass | fail | missing |
|
||||
| build_test | docs/build-test-reports/<feature-id>-build-test.md | pass-for-reference-verification | <status> | pass | fail | missing |
|
||||
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <status> | pass | fail | missing |
|
||||
| physics_evaluation | docs/physics-evaluations/<feature-id>-physics-evaluation.md | pass-for-release-agent | <status> | pass | fail | missing |
|
||||
|
||||
## Acceptance Traceability
|
||||
|
||||
| requirement_id | acceptance_criterion | test_id | reference_model_id | verification_report | release_disposition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| <req-id> | <criterion> | <test-id> | <model-id> | <report path> | released | deferred | blocked |
|
||||
|
||||
## Validation Evidence
|
||||
|
||||
| command_or_report | expected | observed | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Build/Test report의 config-resolved CMake/MSVC/CTest | pass | <result> | <summary> |
|
||||
| Harness Python pytest (when applicable) | pass or N/A | <result> | <summary> |
|
||||
| reference verification | pass-for-physics-evaluation | <status> | <summary> |
|
||||
| physics evaluation | pass-for-release-agent | <status> | <summary> |
|
||||
|
||||
## Known Limitations
|
||||
|
||||
| limitation | category | user_impact | disposition |
|
||||
| --- | --- | --- | --- |
|
||||
| <unsupported Abaqus keyword or solver scope limit> | input | physics | numerical | output | <impact> | documented | deferred | blocker |
|
||||
|
||||
## Release Notes Draft
|
||||
|
||||
### Feature Summary
|
||||
- <user-facing summary>
|
||||
|
||||
### Verification Scope
|
||||
- <validated analysis, element, material, I/O, reference model scope>
|
||||
|
||||
### Main Limitations
|
||||
- <known limitation>
|
||||
|
||||
### Artifacts
|
||||
- <release report, reference bundle, verification report paths>
|
||||
|
||||
## Release Verdict
|
||||
- verdict: ready-for-release | needs-correction | needs-reference-verification | needs-physics-evaluation | needs-documentation | needs-upstream-decision | blocked
|
||||
- reason: <short reason>
|
||||
|
||||
## Handoff Recommendation
|
||||
|
||||
| target_agent | reason | required_input |
|
||||
| --- | --- | --- |
|
||||
| Coordinator Agent | <release decision or blocked issue> | <summary> |
|
||||
| Correction Agent | <implementation-owned release blocker> | <failure evidence> |
|
||||
| Reference Verification Agent | <missing or failed reference comparison> | <artifact and report gap> |
|
||||
| Physics Evaluation Agent | <missing or failed physics evaluation> | <reference verification evidence> |
|
||||
| Requirement Agent | <requirement or acceptance gap> | <open decision> |
|
||||
| I/O Definition Agent | <I/O scope or Abaqus keyword limitation gap> | <contract gap> |
|
||||
| Reference Model Agent | <missing required input/CSV or comparison mapping> | <exact gap> |
|
||||
|
||||
## 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
|
||||
- <missing evidence, contradictory upstream report, unresolved defect, missing required comparison file/mapping, or documentation gap>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
|
||||
- `ready-for-release`: required gate가 모두 통과했고, 모든 `must` requirement traceability와 known limitations 문서화가 완료되었다.
|
||||
- `needs-correction`: implementation-owned defect 또는 unresolved test/build/reference/physics issue가 있어 Correction Agent가 필요하다.
|
||||
- `needs-reference-verification`: reference verification report가 없거나 `pass-for-physics-evaluation`이 아니다.
|
||||
- `needs-physics-evaluation`: physics evaluation report가 없거나 `pass-for-release-agent`가 아니다.
|
||||
- `needs-documentation`: gate evidence는 통과했지만 release scope, known limitations, release notes, traceability 문서가 불완전하다.
|
||||
- `needs-upstream-decision`: requirement, tolerance, required comparison file/mapping, I/O, acceptance evidence가 누락되었거나 상충한다.
|
||||
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- `ready-for-release`는 Build/Test, Reference Verification, Physics Evaluation gate evidence가 모두 present and passing일 때만 사용할 수 있다.
|
||||
- 모든 `must` requirement는 acceptance criterion, test/reference evidence, release scope에 trace되어야 한다.
|
||||
- known limitations와 deferred/open issue는 Release Notes Draft에 명확히 기록되어야 한다.
|
||||
- missing evidence, contradictory upstream reports, unresolved defects, missing declared comparison
|
||||
files는 적절한 `needs-*` 상태로 분류한다. Canonical naming, README, metadata, provenance와
|
||||
unrequested portfolio는 blocker가 아니다.
|
||||
- 이 문서는 FESA 내부 feature release readiness 판정을 위한 것이며, 외부 publish/deploy/package/tag/commit 자동화는 포함하지 않는다.
|
||||
@@ -1,123 +0,0 @@
|
||||
# 요구조건 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Requirement Agent가 작성하거나 제안한 기능별 요구조건 문서를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/requirements/<feature-id>.md` 형식을 사용한다. 각 문서는 구현 전에 작성되며, Formulation Agent, I/O Definition Agent, Reference Model Agent, Implementation Planning Agent가 이어받을 수 있는 검증 가능한 baseline이어야 한다.
|
||||
|
||||
## Requirement Agent 역할
|
||||
|
||||
Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 바꾼다.
|
||||
|
||||
수행한다:
|
||||
- 기능 범위, 제외 범위, 입력, 출력, 제약조건을 정의한다.
|
||||
- 해석 타입, 대상 요소, 자유도, 재료 모델, 경계조건, 하중 조건을 명확히 한다.
|
||||
- 절점 변위, 반력, 요소 내력, 응력 등 검증 물리량을 정한다.
|
||||
- tolerance와 reference artifact 요구사항을 기록한다.
|
||||
- Requirement Verification Matrix를 작성한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 유한요소 정식화를 확정하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- 기능 완료 여부를 승인하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Requirements
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- title: <title>
|
||||
- status: draft | needs-user-decision | approved
|
||||
- owner_agent: requirement-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Purpose
|
||||
<기능 목적과 사용자/개발자 관점의 기대 동작>
|
||||
|
||||
## In Scope
|
||||
- <포함 범위>
|
||||
|
||||
## Out Of Scope
|
||||
- <제외 범위>
|
||||
|
||||
## Analysis Definition
|
||||
- analysis_type: linear static | nonlinear static | modal | other
|
||||
- elements: <대상 요소>
|
||||
- dofs: <자유도>
|
||||
- material_model: <재료 모델>
|
||||
- boundary_conditions: <경계조건>
|
||||
- loads: <하중 조건>
|
||||
- coordinate_system: <좌표계>
|
||||
- units: <단위계>
|
||||
|
||||
## Input Requirements
|
||||
- <입력 요구조건>
|
||||
|
||||
## Output Requirements
|
||||
- <출력 요구조건>
|
||||
|
||||
## Verification Quantities
|
||||
- nodal_displacement: required | not-applicable
|
||||
- reaction: required | not-applicable
|
||||
- element_internal_force: required | not-applicable
|
||||
- stress: required | not-applicable
|
||||
- strain: required | not-applicable
|
||||
- energy_or_residual: required | not-applicable
|
||||
|
||||
## Tolerance Policy
|
||||
- absolute_tolerance: <value or TBD>
|
||||
- relative_tolerance: <value or TBD>
|
||||
- norm_based_tolerance: <value or TBD>
|
||||
|
||||
## Reference Case Requirements
|
||||
|
||||
- input_path: <exact existing `.inp` path or N/A>
|
||||
- required_csv_paths: <only blocking/warning quantity CSV paths or N/A>
|
||||
- blocking_quantities: <components or N/A>
|
||||
- warning_only_quantities: <components or N/A>
|
||||
- hdf5_projection: <dataset or N/A>
|
||||
- source_id_component_matching: <rule or N/A>
|
||||
- row_precheck: missing/extra/duplicate/nonfinite fail before tolerance
|
||||
- tolerance: <approved formula or N/A>
|
||||
|
||||
Canonical naming, README, metadata, provenance, duplicated units/coordinates/step-frame fields,
|
||||
CSV schema versions와 비교하지 않는 quantity CSV는 기본 요구조건이 아니다.
|
||||
|
||||
## Requirement Verification Matrix
|
||||
|
||||
| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| FESA-REQ-<FEATURE>-001 | The FESA solver shall ... | functional | ... | user | must | reference-comparison | ... | ... | Reference Model Agent; Implementation Planning Agent | draft |
|
||||
|
||||
## Open Questions
|
||||
- <미확정 값 또는 사용자 결정 필요 사항>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Research Agent
|
||||
- <조사할 이론, 논문, benchmark, 표준>
|
||||
|
||||
### Formulation Agent
|
||||
- <정식화 단계에 넘길 해석 타입, 요소, 재료, 자유도, 출력 물리량 계약>
|
||||
|
||||
### I/O Definition Agent
|
||||
- <입력/출력 schema 요구조건>
|
||||
|
||||
### Reference Model Agent
|
||||
- <exact input/required CSV paths, blocking/warning quantities, matching, tolerance>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <먼저 작성할 테스트와 acceptance criteria>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` 요구조건은 검증 방법과 acceptance criteria를 가져야 한다.
|
||||
- 모든 수치 요구조건은 단위, 좌표계, tolerance 또는 `TBD with owner`를 가져야 한다.
|
||||
- reference 비교가 필요한 요구조건은 필요한 CSV artifact를 명시해야 한다.
|
||||
- "빠르게", "정확하게", "Abaqus처럼" 같은 문장은 검증 가능한 기준으로 바꾸거나 open question으로 남겨야 한다.
|
||||
- 구현 방법, 정식화 세부식, C++ API는 이 문서에서 확정하지 않는다.
|
||||
@@ -1,108 +0,0 @@
|
||||
# 연구 브리프 작성 가이드
|
||||
|
||||
이 디렉터리는 Research Agent가 작성하거나 제안한 기능별 연구 브리프를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/research/<feature-id>-research.md` 형식을 사용한다. 각 브리프는 Requirement Agent의 요구조건을 입력으로 받아 Formulation Agent, Numerical Review Agent, Reference Model Agent, Implementation Planning Agent가 사용할 수 있는 근거 자료를 제공해야 한다.
|
||||
|
||||
## Research Agent 역할
|
||||
|
||||
Research Agent는 FEM 이론, benchmark, verification reference, solver manual, 논문 자료를 조사한다.
|
||||
|
||||
수행한다:
|
||||
- 기능 요구조건과 관련된 이론 자료를 조사한다.
|
||||
- 요소별 benchmark, patch test, MMS, MES, convergence study 후보를 찾는다.
|
||||
- Abaqus/Nastran 결과와 비교 가능한 공개 benchmark 또는 문헌 해를 정리한다.
|
||||
- 자료의 신뢰도, 적용 범위, 한계, 상충 여부를 평가한다.
|
||||
- downstream agent가 사용할 수 있도록 출처와 근거를 추적 가능하게 남긴다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 유한요소 정식화를 확정하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- 기능 완료 여부를 승인하지 않는다.
|
||||
|
||||
## Source Reliability Tier
|
||||
|
||||
| tier | source type | examples | use |
|
||||
| --- | --- | --- | --- |
|
||||
| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, official solver manuals | 우선 근거 |
|
||||
| Tier 2 | peer-reviewed paper, reproducible arXiv preprint, textbook | MMS/MES 논문, finite element textbook | 이론/검증 후보 |
|
||||
| Tier 3 | vendor example, university course note, technical blog | 공개 강의노트, 기술 블로그 | 보조 근거 |
|
||||
| Reject | forum answer, LLM summary, unsourced page, illegal PDF mirror, citation 없는 wiki성 문서 | forum, mirror PDF, 출처 없는 요약 | primary evidence로 사용 금지 |
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Research Brief
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- status: draft | needs-user-decision | ready-for-formulation
|
||||
- owner_agent: research-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Research Questions
|
||||
- <Requirement Agent 또는 사용자가 넘긴 조사 질문>
|
||||
|
||||
## Source Inventory
|
||||
|
||||
| source_type | title | author_or_org | URL_or_DOI | access_date | reliability_tier | notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| standard | ASME V&V 10 | ASME | <URL> | <YYYY-MM-DD> | Tier 1 | VVUQ framework |
|
||||
|
||||
## Extracted Facts
|
||||
- <정식화에 필요한 사실, benchmark 조건, 검증 물리량, 재료/좌표/단위 가정>
|
||||
|
||||
## Candidate Benchmarks
|
||||
|
||||
| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| <id> | <source title> | analytical \| NAFEMS \| Abaqus Verification/Benchmark \| NASA/FEMCI \| paper-derived | <physics> | <targets> | <needed artifacts> | <limits> |
|
||||
|
||||
## Verification Relevance
|
||||
- code_verification: <관련성>
|
||||
- solution_verification: <관련성>
|
||||
- validation: <관련성>
|
||||
- reference_comparison: <관련성>
|
||||
|
||||
## Applicability Limits
|
||||
- linear_or_nonlinear: <scope>
|
||||
- deformation: small | large | TBD
|
||||
- element_type: <scope>
|
||||
- material_model: <scope>
|
||||
- geometry: <scope>
|
||||
- boundary_conditions: <scope>
|
||||
- loads: <scope>
|
||||
- coordinate_system: <scope>
|
||||
- units: <scope>
|
||||
|
||||
## Open Issues
|
||||
- <근거 부족, 상충 자료, 유료/비공개 자료, 사용자 결정 필요 사항>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Formulation Agent
|
||||
- <이론 사실, governing assumptions, candidate equations, unresolved formulation questions>
|
||||
|
||||
### Numerical Review Agent
|
||||
- <수치 위험, convergence expectations, patch test/MMS/MES evidence, source disagreements>
|
||||
|
||||
### Reference Model Agent
|
||||
- <benchmark candidates, required reference artifacts, target quantities, source limitations>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <verification scenarios and testable acceptance evidence>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 외부 근거는 source metadata와 reliability tier를 가져야 한다.
|
||||
- verified fact와 inference를 구분해야 한다.
|
||||
- benchmark 후보는 target quantity와 applicability limit을 가져야 한다.
|
||||
- Abaqus Benchmarks Guide와 Abaqus Verification Guide의 용도를 구분해야 한다.
|
||||
- NAFEMS benchmark는 independent standard test와 target value 후보로 기록해야 한다.
|
||||
- MMS/MES 자료는 code verification 후보로 기록하되 정식화 확정으로 취급하지 않는다.
|
||||
- 사용 불가능하거나 유료/비공개인 자료는 Open Issues에 남겨야 한다.
|
||||
Reference in New Issue
Block a user