FESADev/docs/build-test-reports/README.md

# 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한다.