# Harness 동작 과정

## 개발 작업과 명시적 검증

메인 assistant가 관련 계약과 변경 범위를 확인하고 필요한 전문 작업만 위임한다.
현재 역할과 사용자 결정 경계는 [Agent 운영](SOLVER_AGENT_DESIGN.md),
문서 관리는 [Feature 문서 관리](FEATURE_DOCUMENTATION.md),
운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다.

```text
관련 계약·현재 evidence 확인 → 변경 → 관련 test/build → 결과 확인
                                 │
                                 └─ 기능 완료 시 전체 build/test·필수 reference 비교
```

동작 변경에는 해당 의미를 확인하는 테스트를 추가·수정한다. 버그는 가능한 경우 실패를
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적인
새 테스트를 요구하지 않는다. 계획·소스·테스트·evidence는 할당된 범위 안에서 변경한다.

개발 중 focused check는 실제 configured backend 명령으로 수행한다.
`python scripts/execute.py`는 구성된 전체 build/test를 한 번 실행한다. 사용자가 요청하거나
넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되, 이후 변경·실패가 없으면 반복하지
않는다. 계획 작성만 요청받은 경우에는 실행하지 않는다.

## 변경 종류별 검증

| 작업 | 수행할 작업과 확인 |
| --- | --- |
| 문서 수정 | 관련 문서·소스·링크·diff 정적 확인. Solver build, 새 테스트, 별도 specialist 호출을 의무화하지 않음 |
| 일반 구현 버그 | 메인 또는 기존 구현 owner가 가능한 실패 재현 → 최소 수정 → 관련 검사. 변경 영향·기능 완료 조건에 따라 전체 검증 |
| 새 수치 기능 | 필요한 요구·정식화·I/O 정의, 독립 numerical review → 구현·관련 테스트 → 전체 build/test와 필수 analytical/invariant·물리·reference 검증 |

수식·요소·재료·적분·상태 갱신 변경에는 독립 numerical review를 수행한다. 물리/수치
검증은 각 계약에 따라 수행하며 역할이나 보고서 수를 줄였다는 이유로 생략하지 않는다.
Release-readiness 감사는 명시적으로 요청할 때만 수행한다.

## Runner의 실행 순서

[Runner](../scripts/execute.py)는 자신의 경로에서 저장소 root를 정한 뒤 아래를 수행한다.

1. [Config](../scripts/msvc_harness/config.py)를 읽고 타입·허용 field·경로·preset 조합을 확인한다.
2. [Discovery](../scripts/msvc_harness/discovery.py)가 명시된 projectType 또는 CMake/MSBuild metadata로 backend를 선택한다.
3. [Toolchain](../scripts/msvc_harness/toolchain.py)이 필요한 Visual Studio/MSBuild·CMake/CTest 도구를 찾는다.
4. 선택된 adapter가 argv·cwd·stage·timeout·결과 검사를 포함한 검증 계획을 만든다.
5. [Process](../scripts/msvc_harness/process.py)가 명령을 순서대로 실행하고 각 결과를 검사한다.
6. 성공 시 실행한 명령·cwd·exit code와 test 출력 요약을 반환한다. 실패 시 원인 진단과 nonzero를 반환한다.

여기서 검증 계획은 backend 명령 목록이다. Feature phase/index/step 파일이나 LLM
프롬프트가 아니다. Runner는 Git branch·HEAD·index를 관리하거나 Feature 문서를
해석해 추가 명령을 생성하지 않는다.

### Backend별 실행

| Backend | 실행과 결과 검사 |
| --- | --- |
| CMake/CTest | configure → compiler metadata의 MSVC 확인 → build → CTest JSON discovery/0개 거부 → test |
| MSBuild | 선택된 solution/project build → 명시된 repository-relative testCommand 실행 |

FESA는 CMake/MSVC x64/Debug와 CTest를 제품 검증 기준으로 사용한다.
MSBuild adapter가 있다는 사실이 solution-only 검증을 대체 승인하지 않는다.
Preset 선택과 정확한 명령·설정 예시는 [Harness 운영 가이드](HARNESS.md)를 따른다.

## 실행 경계와 실패 처리

Config의 경로와 명령 cwd는 repository 범위 안인지 확인한다. MSBuild testCommand의
실행 파일도 repository-relative 경로여야 한다. Subprocess는 argv 배열과 `shell=False`로
실행하며 stdout/stderr를 수집한다. Config·preset·실행 파일 자체의 side effect까지 격리하는
sandbox는 아니므로 실제 실행 입력과 도구 권한을 확인한다.

전체 deadline은 시작부터 1,800초다. 각 명령의 timeout은 남은 전체 시간과 명령별 제한 중
짧은 값이며, 실행 전 남은 시간이 없으면 실패한다. Backend nonzero, timeout, MSVC 확인
실패나 CTest 0개 등 결과 검사 실패가 발생하면 후속 단계를 실행하지 않는다.

명령 실패 진단에는 stage·argv·cwd, 가능한 원래 exit code와 출력 tail이 포함된다.
현재 구현 owner가 원인을 확인하고 필요한 수정 또는 환경 조치 후 관련 검사를 수행한다.
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않으며 자동 transport retry나
별도 correction 예산은 없다.

Runner는 성공 시 exit 0, config/toolchain/backend 등 실행 실패 시 exit 1을 반환한다.
자동 감지에서 metadata가 없거나 CLI 인자가 잘못되면 exit 2다. 명시된 projectType에 필요한
metadata가 없는 경우는 exit 1이다. Backend 원래 nonzero와 runner exit를 구분한다.
전체 목록은 [결과와 실패 진단](HARNESS.md#결과와-실패-진단)을 참조한다.

## 수치 evidence와 완료 확인

Harness 성공은 build/test 실행 결과다. 필요한 reference comparison을 자동 탐색하거나
솔버 correctness 전체를 판정하지 않는다. 메인·구현 담당자는 계약이 요구하는 다음
검증을 별도로 확인한다.

- Unit·coordinate·부호·DOF/component·source identity와 결과 위치의 일치
- Analytical solution, invariant·equilibrium·energy·convergence 등 적용되는 검증
- Missing·extra·duplicate·nonfinite required row를 tolerance 전에 거부하는 비교
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature의 비교량·판정 구분
- Trial/committed state·실패 보존·결정론과 필요한 독립 물리 판단

Reference artifact와 tolerance를 통과에 맞춰 수정하지 않는다. 명령·exit code와 결정적
판정값은 필요한 보고서에 한 번 기록하고 원시 로그는 원본 경로로 연결한다. 실패·미실행·
stale evidence와 미해결 항목을 명확히 남기며 검사를 생략한 사실을 통과로 보고하지 않는다.

## 과거 phase·hook·Git 처리

현재 runner는 내부 Codex 세션, phase 상태기계·result payload, `owned_paths`·
`attempt_history`, 자동 branch/commit/push, PreToolUse/Stop을 사용하지 않는다.
`coordination.md`와 기존 phase·hook 기록은 이력으로 보존하고 새 실행 입력으로 만들지 않는다.

옛 phase/push/권한 상승 CLI와 legacy `tdd` 설정의 처리는
[이전 운영 방식 안내](HARNESS.md#이전-운영-방식에서-달라진-점)를 따른다.
사용자 config와 이력을 자동 migration하거나 실패 evidence를 지우지 않는다.
로컬 검증은 commit·push·tag·release 또는 외부 solver 실행 권한을 부여하지 않는다.