# Build/Test Report 문서 작성 가이드

이 디렉터리는 Build/Test Executor Agent가 작성하거나 제안하는 기능별 build/test 실행 리포트를 보관하는 위치다.

Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 Fortran no-Abaqus validation, reference artifact validation, workspace validation을 실행하고, 실패를 분류해 다음 agent로 handoff한다. 이 agent는 source code, tests, 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 해석을 직접 실행하지 않는다.
- reference CSV를 생성하지 않는다.
- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
- 최종 reference verification report를 작성하지 않는다.

## 실행 순서

기본 순서는 implementation plan/report에 따라 다음 중 필요한 항목만 실행한다.

```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_fortran.py
python scripts/validate_reference_artifacts.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도 없으면 안내 메시지와 함께 성공 종료

For Abaqus UserSubroutine work, workspace validation also supports:

- `HARNESS_FORTRAN_VALIDATION=off|detect|auto|compile`
- `HARNESS_FORTRAN_COMPILER=auto|ifx|ifort`
- `HARNESS_ONEAPI_VARS_BAT=<path>`
- `HARNESS_ABAQUS_VALIDATION=off|detect|run`
- `HARNESS_ABAQUS_COMMAND=<path-or-name>`
- `HARNESS_ABAQUS_VALIDATION_COMMANDS=<newline commands>`
- `HARNESS_ABAQUS_USE_ONEAPI_ENV=auto|on|off`

Default validation does not run Abaqus jobs. Solver-result evidence must come from externally generated ODB-extracted CSV artifacts.

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

```powershell
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
```

## 문서 템플릿

```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: 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한다.