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를 실행하지 않는다.
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 우선순위는 다음과 같다.

HARNESS_VALIDATION_COMMANDS
CMakePresets.json의 msvc-debug
기본 CMake/MSVC x64 Debug 명령
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한다.