FESADev/docs/build-test-reports

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 artifacts와 test outputs는 build/ 아래 생성될 수 있다.

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

Build/Test Executor Agent 역할

수행한다:

• python scripts/validate_workspace.py를 기본 검증 명령으로 실행한다.
• implementation plan/report에 명시된 경우 harness self-test와 feature-specific CTest를 실행한다.
• HARNESS_VALIDATION_COMMANDS, CMakePresets.json의 msvc-debug, 기본 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에 따라 다음 중 필요한 항목만 실행한다.

python -m unittest discover -s scripts -p "test_*.py"
ctest -C Debug -R <feature-or-label>
python scripts/validate_workspace.py

scripts/validate_workspace.py의 command discovery 우선순위는 다음과 같다.

1. HARNESS_VALIDATION_COMMANDS
2. CMakePresets.json의 msvc-debug
3. 기본 CMake/MSVC x64 Debug 명령
4. CMakeLists.txt가 없고 override도 없으면 안내 메시지와 함께 성공 종료

기본 CMake/MSVC x64 Debug 명령은 다음과 같다.

cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
cmake --build build/msvc-debug --config Debug
ctest --test-dir build/msvc-debug --output-on-failure -C Debug

문서 템플릿

# <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: build/msvc-debug | <observed build dir>
- active_override_env_vars: HARNESS_VALIDATION_COMMANDS | HARNESS_CMAKE_GENERATOR | HARNESS_CMAKE_PLATFORM | HARNESS_CMAKE_CONFIG | HARNESS_BUILD_DIR | none
- command_discovery_path: HARNESS_VALIDATION_COMMANDS | CMakePresets.json msvc-debug | default CMake/MSVC x64 Debug | no-CMake informational success

## Command Log Summary

| order | command | exit_code | duration | stdout_stderr_tail |
| --- | --- | --- | --- | --- |
| 1 | python -m unittest discover -s scripts -p "test_*.py" | <code> | <duration> | <tail summary> |
| 2 | ctest -C Debug -R <feature-or-label> | <code> | <duration> | <tail summary> |
| 3 | python scripts/validate_workspace.py | <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 실패를 구분한다.
• no-CMake 상황은 scripts/validate_workspace.py 정책대로 안내 메시지와 성공 종료로 기록한다.
• 성공 판정은 build/test 통과까지만 의미한다.
• reference tolerance, physics validation, release readiness는 판정하지 않는다.
• upstream 계약 문제는 Implementation Agent에 임의 수정으로 넘기지 않고 적절한 upstream agent로 handoff한다.