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 해석을 직접 실행하지 않는다.
reference CSV를 생성하지 않는다.
release readiness, reference tolerance success, physics validation success를 승인하지 않는다.
최종 reference verification report 또는 physics validation report를 작성하지 않는다.

실행 순서

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

TRIAGE -> MINIMAL FIX -> VERIFY -> REPORT

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

<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: Fortran 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 불일치 또는 누락

문서 템플릿

# <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 Fortran 수정에는 관련 테스트 또는 기존 실패 테스트가 있어야 한다.
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는 판정하지 않는다.