FESADev/docs/corrections/README.md

# Correction Report 문서 작성 가이드

이 디렉터리는 Correction Agent가 작성하거나 제안하는 기능별 correction report를 보관하는 위치다.

Correction Agent는 Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent가 전달한 실패를 triage하고, implementation-owned failure만 최소 수정으로 복구한다. 이 agent는 source, header, test, CMake 수정은 수행할 수 있지만 requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.

기본 문서명은 `docs/corrections/<feature-id>-correction.md` 형식을 사용한다.

## Correction Agent 역할

수행한다:
- 실패 로그와 implementation report를 읽고 failure classification을 먼저 확정한다.
- configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
- implementation-owned failure에 한해 source/header/test/CMake를 최소 수정한다.
- 수정 후 targeted command를 먼저 실행하고 `python scripts/validate_workspace.py`를 실행한다.
- harness, hook, agent config 관련 수정에서는 `python -m unittest discover -s scripts -p "test_*.py"`도 실행한다.
- 반복 실패 또는 upstream 계약 문제를 Coordinator Agent나 관련 upstream agent로 handoff한다.

수행하지 않는다:
- requirements를 수정하지 않는다.
- formulations를 수정하지 않는다.
- I/O contracts를 수정하지 않는다.
- numerical review reports를 수정하지 않는다.
- reference artifacts를 수정하지 않는다.
- tolerance policies를 수정하지 않는다.
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
- reference CSV를 생성하지 않는다.
- release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
- 최종 reference verification report 또는 physics validation report를 작성하지 않는다.

## 실행 순서

Correction Agent는 항상 다음 순서를 따른다.

```text
TRIAGE -> MINIMAL FIX -> VERIFY -> REPORT
```

기본 검증 명령은 다음과 같다.

```powershell
<targeted command that reproduced the failure>
python scripts/validate_workspace.py
python -m unittest discover -s scripts -p "test_*.py"
```

`python -m unittest discover -s scripts -p "test_*.py"`는 harness, hook, agent config, Python validation behavior가 correction 범위에 포함될 때 실행한다.

## Failure Classification

- `configure`: CMake configure, preset, generator, cache setup 실패
- `compile`: C++ compilation 실패
- `link`: linker, symbol resolution, target dependency 실패
- `test`: CTest, unit, integration, parser/I/O, ordinary regression test 실패
- `reference-comparison`: 저장된 reference artifact와 deterministic comparison 실패
- `harness`: Python harness self-test, TDD guard, hook, validation script 실패
- `environment`: MSVC, CMake, Python, path, permission, generator, local dependency 문제
- `upstream-contract`: requirements, formulation, I/O, reference artifact, tolerance, implementation plan 불일치 또는 누락

## 문서 템플릿

```markdown
# <feature title> Correction Report

## Metadata
- feature_id: <feature-id>
- source_failure_report: docs/build-test-reports/<feature-id>-build-test.md | <reference/physics report path>
- source_implementation_report: <path or N/A>
- source_implementation_plan: docs/implementation-plans/<feature-id>-implementation-plan.md
- status: corrected-for-build-test | corrected-for-reference-verification | needs-build-test-rerun | needs-environment-fix | needs-upstream-decision | blocked
- owner_agent: correction-agent
- date: <YYYY-MM-DD>

## Failure Triage
- classification: configure | compile | link | test | reference-comparison | harness | environment | upstream-contract
- first_failed_command: <command>
- failed_target_or_test: <target, test, label, or N/A>
- evidence_tail: <short relevant tail, not full log>
- triage_decision: implementation-owned | environment-owned | upstream-owned | blocked

## Root Cause Summary
- root_cause_type: implementation defect | test defect | CMake registration issue | environment issue | upstream-contract issue
- summary: <short explanation>
- why_minimal_fix_is_allowed: <contract or failure evidence>

## Correction Scope

| file | change_type | reason | in_scope |
| --- | --- | --- | --- |
| include/fesa/<module>/<file>.hpp | source/header | <reason> | true |
| src/<module>/<file>.cpp | source | <reason> | true |
| tests/<module>/<file>_test.cpp | test | <reason> | true |
| CMakeLists.txt | CMake | <reason> | true |

Excluded files:
- requirements: unchanged
- formulations: unchanged
- I/O contracts: unchanged
- reference artifacts: unchanged
- tolerance policies: unchanged

## Verification Evidence

| order | command | exit_code | result | evidence |
| --- | --- | --- | --- | --- |
| 1 | <targeted command> | <code> | pass | fail | <summary> |
| 2 | python scripts/validate_workspace.py | <code> | pass | fail | <summary> |
| 3 | python -m unittest discover -s scripts -p "test_*.py" | <code or skipped> | pass | fail | skipped | <summary> |

## Traceability

| requirement_id | task_id | test_id | failing_command | corrected_file | acceptance_criterion |
| --- | --- | --- | --- | --- | --- |
| <req-id or N/A> | <task-id or N/A> | <test-id or N/A> | <command> | <file> | <criterion> |

## Handoff Recommendation

| target_agent | reason | required_input |
| --- | --- | --- |
| Build/Test Executor Agent | <independent full validation required> | <commands and correction summary> |
| Reference Verification Agent | <reference comparison rerun required> | <corrected-for-reference-verification evidence> |
| Physics Evaluation Agent | <physics sanity rerun required> | <corrected solver behavior evidence> |
| Implementation Agent | <new implementation task required> | <unfixed implementation gap> |
| upstream agent | <contract issue> | <required upstream decision> |
| Coordinator Agent | <repeated failure or blocked state> | <classification history and stop condition> |

## Stop Condition
- repeated_failure: true | false
- upstream_ambiguity: true | false
- reference_artifact_gap: true | false
- environment_blocker: true | false
- next_required_decision: <decision or N/A>
```

## 상태 값

- `corrected-for-build-test`: correction이 Build/Test Executor Agent 재실행 단계로 넘어갈 수 있다.
- `corrected-for-reference-verification`: correction이 Reference Verification Agent 재실행 단계로 넘어갈 수 있다.
- `needs-build-test-rerun`: targeted correction은 통과했지만 독립 build/test 재실행이 필요하다.
- `needs-environment-fix`: 로컬 toolchain, generator, Python, path, permission 문제가 correction 또는 verification을 막는다.
- `needs-upstream-decision`: upstream contract, reference artifact, tolerance, formulation ambiguity가 안전한 수정을 막는다.
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.

## 품질 기준

- 수정 전 failure classification을 기록해야 한다.
- 모든 변경은 실패 로그 또는 implementation plan acceptance criterion에 trace되어야 한다.
- production C++ 수정에는 관련 테스트 또는 기존 실패 테스트가 있어야 한다.
- requirements, formulations, I/O contracts, reference artifacts, tolerance policies는 수정하지 않는다.
- 실패 로그는 전체 원문을 복제하지 않고 핵심 tail과 원인 요약만 기록한다.
- 동일 classification이 두 번 반복되면 Coordinator Agent 또는 관련 upstream agent로 handoff한다.
- 성공 판정은 correction verification까지만 의미한다.
- release readiness, reference tolerance success, physics validation success는 판정하지 않는다.