FESADev/docs/superpowers/plans/2026-09-07-agent-harness-documentation-update.md

# Agent·Harness 경량화 문서 갱신 Implementation Plan

> **For agentic workers:** 후속 실행에는 `superpowers:executing-plans`를 적용하되 아래 문서 작업을 메인이 직접 수행한다. 고정 solver stage, task별 새 subagent·reviewer, 자동 commit을 추가하지 않는다.

**Goal:** 승인된 Agent·Harness 경량화를 FESA의 공통 문서 10개에 반영하여 현재 운영 지침과 구현의 불일치를 없앤다.

**Architecture:** `docs2/agent-harness-simplification`의 승인된 운영 변경을 현재 `.agents`, `.codex`, `scripts`에 대조하여 반영한다. FESA 제품·수치·입출력·C++ 계약은 유지하고, 공통 ADR에는 기존 결정과 구분되는 후속 결정을 기록한다.

**Tech Stack:** 한국어 Markdown, PowerShell 기반 정적 확인. 문서에 설명할 검증 환경은 기존 CMake/MSVC x64/Debug, CTest, Python Harness다.

**Spec:** [경량화 PRD](../../../docs2/agent-harness-simplification/PRD.md), [AH-01~05 결정](../../../docs2/agent-harness-simplification/ADR.md), [승인 계획 보존본](../../../docs2/agent-harness-simplification/implementation-details.md), [기존 구현 보고서](../../../docs2/agent-harness-simplification/implementation-report.md).

작성일: 2026-09-07. 상태: **문서 갱신 계획안**. 이번 요청에서는 이 계획만 작성하며 대상 문서를 수정하거나 Harness를 실행하지 않는다. 아래 checkbox는 후속 문서 작업의 완료 조건이다.

## 1. 범위와 기준

### Global Constraints

- 후속 수정 범위는 사용자가 지정한 `AGENTS.md`와 `docs/` 문서 9개로 제한한다. 정확한 목록은 §3을 따른다.
- 현재 사용자의 `.agents`, `.codex`, `.harness`, `scripts`, `docs2` 변경을 보존한다. 이 계획으로 구현·테스트·설정·phase 이력을 수정하지 않는다.
- FESA의 C++17 이상, CMake/MSVC/x64/Debug, MKL/TBB/HDF5와 승인된 Abaqus 입력 subset을 유지한다.
- HDF5 `<stem>_results.h5`의 lexical sibling 경로, source identity, 결정론, state/output 보존, 기존 B33/MITC4 비교량·판정 구분을 유지한다.
- [TOLERANCE](../../TOLERANCE.md), reference artifact와 solver 구현은 수정 대상이 아니다. 수치 검토와 필요한 analytical/invariant·reference 검증을 유지한다.
- 운영 간소화를 이유로 물리 의미, 공개 schema, 지원 범위, tolerance, 외부 실행·원격·파괴 작업 권한을 확대하지 않는다.
- 작은 문서 작업에는 solver Feature 폴더·관리 문서·stage 보고서를 새로 만들지 않는다. 이 계획도 별도 solver Feature workflow를 시작하지 않는다.
- 문서만 갱신하므로 새 테스트, pytest, Harness, CMake/CTest, 수동 hook을 실행하지 않는다. 확인 범위는 문서·링크·설정·소스의 정적 대조다.
- 기존 문서의 언어·구성을 가능한 한 유지한다. 문서 전체 복사나 요청과 무관한 코딩 규약 정리는 하지 않는다.

### 근거의 적용 순서

1. 현재 사용자가 요청한 문서 갱신 범위와 경량화 목적.
2. `docs2/agent-harness-simplification`에 기록된 AH-01~05의 운영 변경과 유지할 acceptance.
3. 현재 저장소의 실제 agent/skill profile, runner, config/discovery/adapter/process 구현.
4. 기존 FESA 제품·수치·아키텍처 계약과 현재 preset. 구현이 이 계약을 변경할 권한은 없다.

`docs2`의 공통 문서는 문안 참고 자료다. 기존 FESA 문서를 통째로 대체하는 원본으로 사용하지 않는다. 승인 설명과 현재 구현이 다르면 운영 의도와 관찰된 동작을 구분하고, 문서로 미구현 기능이나 검증 통과를 선언하지 않는다.

## 2. 현재 확인한 차이와 반영 판단

| 근거 | 확인한 내용 | 문서 반영 판단 |
| --- | --- | --- |
| [현재 profiles](../../../.codex/agents) | 7개 specialist만 남고 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`다. Implementation profile의 모델은 `gpt-5.6-terra`다. | 삭제된 4개 전용 역할과 일괄 `xhigh` 요구를 제거한다. 모델 선택은 profile로 연결하고 runtime 적용을 검증했다고 주장하지 않는다. |
| [runner](../../../scripts/execute.py), [harness skill](../../../.agents/skills/harness/SKILL.md) | 인자 없는 명시적 검증 실행기다. 내부 LLM, phase 상태 처리, 자동 Git·retry가 없다. | 새 CLI와 현재 exit 의미를 설명한다. 옛 CLI는 폐기 안내에서만 보여 준다. |
| [config](../../../scripts/msvc_harness/config.py), [discovery](../../../scripts/msvc_harness/discovery.py) | legacy `tdd`는 설정 로드 시 안내 후 무시한다. C++ 전체 scan과 orphan-C++ gate가 없다. | 현재 없는 TDD pattern 설정·C++ 파일 scan·자동 skip 설명을 삭제한다. |
| [config 예시](../../../.harness/config.example.json), [presets](../../../CMakePresets.json) | 예시는 `projectType=cmake`, `sourceDir=.`만 지정한다. FESA Ninja preset은 별도로 존재한다. | 예시 복사만으로 Ninja preset을 선택한다고 쓰지 않는다. 명시적 preset 설정 예시를 유지한다. |
| `docs2`의 PRD·ARCHITECTURE·구현 보고서 | solver/build metadata가 없는 framework checkout을 전제로 한다. | 현재 [CMakeLists](../../../CMakeLists.txt), [solver target](../../../src/fesa/CMakeLists.txt), [test target](../../../tests/CMakeLists.txt)이 있으므로 해당 현황 설명은 옮기지 않는다. |
| `docs2`와 현재 공통 ADR | 같은 ADR 번호가 다른 결정을 뜻한다. `docs2` ADR-013은 신뢰 경계이고, 현재 ADR-013은 선형 보 해석 범위다. | 번호를 복사하지 않는다. 현재 문서의 마지막 ID 다음인 ADR-028에서 실제 대체 대상을 명시한다. |
| `docs2`의 구현 보고서와 현재 `tests/` | 보고서의 `test_executor.py` 등과 현재 테스트 파일 구성이 다르며, 현재에는 삭제된 executor/hook을 기대하는 테스트가 남아 있다. | 과거 29건 통과를 현재 checkout의 검증 결과로 사용하지 않는다. 테스트 정합성은 §7의 별도 후속 항목으로 기록한다. |

`docs2/agent-harness-simplification/ADR.md`의 “프로젝트 PRD·ADR 원문 보존”은 이전 구현 범위의 기록이다. 현재 요청은 두 문서의 운영 조항 갱신을 명시적으로 포함하므로 계획에서 제외하지 않는다. 기존 제품 계약과 ADR 결정 본문은 보존하면서 현행 규칙과 대체 관계를 명료하게 만든다.

## 3. 파일별 수정 계획

| 대상 | 변경할 절과 내용 | 보존·확인 기준 |
| --- | --- | --- |
| [AGENTS.md](../../../AGENTS.md) | `문서 기준과 Feature 관리`, `개발 운영 인프라`, `개발 프로세스`, `Agent/Skill Workflow`, `최소 검증 진입점`을 갱신한다. 메인 직접 조정, 조건부 specialist, 핵심 문서 3개·PRD checklist, 간결한 인계, 명시적 검증을 요약한다. 소유권 절의 매 변경 RED·대응 C++ test 강제를 동작 중심 검증으로 바꾸고, reference 변경 권한의 “요청된 phase”를 “명시적으로 요청된 작업 범위”로 고친다. | 제품 정체성, FESA 기술 스택, 수치·선형 정적 불변식, reference 무결성, 사용자 변경 보존을 유지한다. 상세 CLI·workflow를 중복 복사하지 않고 전담 문서에 연결한다. |
| [docs/ADR.md](../../ADR.md) | ADR-028을 추가하고 ADR-012·024~027에 대체/부분 대체 안내를 붙인다. 머리말의 현행 운영 ADR 범위와 ADR-001·002 등의 현행 운영 참조를 확인한다. | 기존 ID와 결정 본문을 소급 재작성하지 않는다. 실제 ADR-013 및 다른 solver 결정은 변경하지 않는다. §4의 대체 범위를 사용한다. |
| [docs/ARCHITECTURE.md](../../ARCHITECTURE.md) | `Solver runtime과 개발 운영 영역`의 개발 흐름, `개발 운영 인프라`의 owner 표·실행 책임, 끝의 Feature 요구사항 원본 설명을 수정한다. 메인, specialist, 명시적 runner, backend adapter/process의 책임을 구분한다. `검증과 reference 경계`의 전문 책임을 필수 agent 순회로 읽히지 않게 정리한다. | Solver runtime 그림·모듈 책임·Domain/AnalysisModel/DofManager·의존성·수명·해석 lifecycle·출력 계약은 보존한다. Runner를 보안 sandbox나 solver correctness 판정기로 표현하지 않는다. |
| [docs/PRD.md](../../PRD.md) | 문서 역할 표의 Feature PRD를 작은 요구사항의 원본으로, `requirements.md`를 필요 시 분리하는 상세 계약으로 바꾼다. `FESA-PRD-GEN-010`은 동작 중심 테스트·가능한 버그 재현과 영향별 검증으로 수정한다. `FESA-PRD-GEN-012`의 evidence를 필수 stage/gate 기록에서 해당 계약의 검증·제한·미해결 항목으로 수정한다. `검증과 완료 기준`의 9단계 순회와 필수 release audit를 제거한다. | GEN-001~009·011과 제품 정의·품질 속성·비목표의 물리/수치 의미를 보존한다. 필요한 독립 수치 검토·물리 검증·reference 비교, 같은 계약을 지지하는 evidence와 stale 판정을 유지한다. |
| [docs/SOLVER_AGENT_DESIGN.md](../../SOLVER_AGENT_DESIGN.md) | 고정 stage·Coordinator 전용 전이·12필드 envelope·5개 outcome 강제·correction signature/budget을 제거한다. 메인의 작업 선택, 7개 specialist 호출 조건/수정 경계/기본 강도, 간단한 dispatch·return, 구현 owner의 실패 수정, 완료 evidence와 사용자 결정 경계를 정의한다. | 새 수식·요소·재료·적분·상태 갱신의 독립 numerical review를 유지한다. 상위 계약 문제의 owner 반환, 무근거 반복 금지, specialist의 범위 제한을 유지한다. |
| [docs/SOLVER_SKILL_DESIGN.md](../../SOLVER_SKILL_DESIGN.md) | `Stage` 중심 inventory를 `사용할 때 / 필요한 입력 / 결과` 중심으로 바꾼다. 8개 FEM skill과 supporting skill을 현재 `SKILL.md`에 맞춘다. implementation skill은 메인도 계획·구현·수정에 사용하고, release skill은 사용자 명시 요청 시에만 사용한다. | `fem-theory-query`의 configured vault 범위, read-only review, tolerance·reference·외부 권한 경계를 유지한다. 모든 문서 재독·공통 outcome/hash·전체 pytest를 문서 편집의 필수 절차로 강제하지 않는다. |
| [docs/HARNESS_WORKFLOW.md](../../HARNESS_WORKFLOW.md) | 요구사항→phase/index/step→Codex→hook→자동 commit 흐름을 관련 계약 확인→변경→관련 검사→기능 완료 시 전체 검사 흐름으로 재구성한다. 현행 runner의 config→discovery→toolchain→adapter→execute_plan 순서와 실패 중단을 설명한다. 문서·일반 버그·새 수치 기능의 3개 사례를 둔다. | 현행 config/경로 검사, MSVC 확인, CTest discovery, timeout·실패 진단은 보존한다. 폐기한 phase schema·출력 JSON·owned_paths·attempt_history를 새 절차에 요구하지 않는다. |
| [docs/HARNESS.md](../../HARNESS.md) | 설치·설정·명령·진단에 집중한다. Harness 실행의 Codex CLI 의존 설명을 제거한다. 인자 없는 CLI, 자동 감지, exit 0/1/2, preset 설정, legacy `tdd`와 옛 CLI 안내를 §5대로 작성한다. hook·sandbox 환경변수·자동 Git·phase 복구·TDD 확장 절을 정리한다. | Windows/MSVC·CMake/CTest·dependency 준비, Python 요구와 재사용 MSBuild adapter 안내를 유지한다. FESA 제품 검증은 CMake/CTest라는 구분을 보존한다. |
| [docs/CODINGSTYLE.md](../../CODINGSTYLE.md) | `Test와 변경 관리` 및 `Implementation Agent Checklist`를 메인/구현 담당자 공통 지침으로 바꾼다. 모든 C++ 변경의 test-file 동반·Step별 RED/full 강제를 영향별 테스트와 검증으로 바꾼다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적 새 테스트를 요구하지 않는다. | PascalCase, include guard, 2-space/80-column, production Doxygen, vendor 경계, 신규 warning 금지 등을 유지한다. B33/MITC4 output 변경의 필수 reference 재검증을 유지한다. |
| [docs/FEATURE_DOCUMENTATION.md](../../FEATURE_DOCUMENTATION.md) | 새 Feature가 필요한 조건과 메인 소유 핵심 문서 3개를 명시한다. 현재 checklist는 PRD 한 곳, 작은 요구사항도 PRD 원본, 별도 requirements/matrix·상세 보고서는 필요한 경우만 생성하도록 바꾼다. 간단한 구현·build/test·reference evidence는 한 보고서에 합칠 수 있게 한다. | `FEATURED_AGENTS.md`의 비자동 로드 성격, 상대 링크, specialist의 할당 문서 소유권과 필수 근거를 유지한다. 기존 `coordination.md`, `docs/features/` 자료는 이력으로 보존하고 신규 상태기계나 일괄 이관을 만들지 않는다. |

## 4. ADR-028에 기록할 결정

제안 제목: **ADR-028: 메인이 필요한 전문 작업을 조정하고 Harness를 명시적 검증 실행기로 사용한다**.

근거는 현재 사용자 요청, 경량화 Feature의 AH-01~05와 실제 source다. 이 계획에서 ADR-028을 이미 작성·승인된 문서처럼 표시하지 않는다. 후속 반영 시 기존 경량화 승인과 이번 문서 동기화 근거를 구분해 연결한다.

| 기존 ADR | 대체할 운영 부분 | 유지되는 부분 |
| --- | --- | --- |
| ADR-012 | 전용 Planning/Executor/Hook 분업과 hook 기반 강제 검증 | 실제 테스트 실행과 단순 파일 존재의 구분, 검증 evidence의 필요성 |
| ADR-024 | 전용 Coordinator, 고정 상태 전이, correction 1회/rerun 1회, 필수 release stage | 승인 범위 안의 자율 작업, 필요한 사용자 결정, 미실행·실패를 통과로 표시하지 않음, 외부 권한 분리 |
| ADR-025 | 관리 문서 4개, `coordination.md` 상태 원본, 모든 요구의 `requirements.md` 분리, 매 dispatch의 전체 bundle 필수화 | 프로젝트/Feature 계약 구분, 전문 문서 소유권, 상대 링크와 중복 방지, 실제 계약 변경에 따른 evidence 영향 확인 |
| ADR-026 | Executor의 Git·transport 관리, hook TDD/Stop, 자체 sandbox 승인 장치 | config/preset/command의 신뢰 경계, 사용자 변경 보존, 실제 runtime 권한, 검증 범위와 미실행의 명확한 보고 |
| ADR-027 | phase Step payload, `owned_paths`, `attempt_history`, 자동 commit 경계와 transport 재시도 계약 | 실패 증거와 사용자 변경을 보존하고 범위 밖 작업을 하지 않는 일반 원칙 |

ADR-028 본문에는 AH-01~05의 효과를 한 번만 기록한다: 메인 orchestration, 명시적 runner, 영향에 맞는 검사, 필요한 문맥만 전달, 핵심 문서 3개와 선택적 상세 기록. 상세 명령과 산출물 형식은 각각 HARNESS·FEATURE_DOCUMENTATION으로 연결한다. 과거 본문의 폐기된 역할/명령 검색 결과는 이력임을 분명히 표시한다.

## 5. 현행 Harness 설명에 넣을 정확한 계약

### 명령과 설정

```powershell
python scripts/execute.py
```

이 명령은 명시적으로 선택/발견한 backend의 전체 검증을 한 번 수행한다. Focused check는 실제 configured backend 명령으로 직접 실행한다. Runner가 Feature 문서에서 reference 명령을 찾아 추가 실행하거나 `phases/`를 읽고 갱신한다고 설명하지 않는다.

FESA Ninja preset을 사용하려면 기존 개인 설정을 보존하면서 다음 필드를 함께 맞춘다. 이번 문서 작업에서 개인 설정은 편집하지 않는다.

```json
{
  "version": 1,
  "projectType": "cmake",
  "cmake": {
    "sourceDir": ".",
    "binaryDir": ".harness/build-ninja-msvc-debug",
    "configurePreset": "windows-msvc-ninja-debug",
    "buildPreset": "windows-msvc-ninja-debug",
    "testPreset": "windows-msvc-ninja-debug"
  }
}
```

현재 `.harness/config.example.json`에는 preset 필드가 없다. `CMakePresets.json`이 존재하거나 예시 설정을 복사했다는 사실만으로 preset이 선택되지는 않는다. Preset 없는 adapter 기본값과 FESA preset 사용법을 구분하여 설명한다.

### 결과와 보장 범위

| 조건 | 현재 동작 |
| --- | --- |
| 구성된 검증이 모두 성공 | runner exit 0, 실행 명령·cwd·exit와 test 출력 요약 |
| config/discovery/toolchain/adapter 오류, backend 실패·timeout, non-MSVC, CTest 0개 등 | runner exit 1. Backend의 원래 nonzero는 진단에 남지만 runner가 같은 숫자를 그대로 반환하는 것은 아님 |
| 자동 감지에서 build metadata 없음 | `not configured`와 exit 2. 검증 통과나 조용한 skip이 아님 |
| 명시한 projectType에 필요한 metadata가 없음 | 잘못된 명시 설정 경로의 실패로 exit 1 |
| 옛 `<phase>`, `--push`, `--approve-danger-full-access` 인자 | argparse usage error, exit 2. 검증을 시작하지 않음 |
| legacy `tdd` 항목 | `load_config` 호출 시 폐기 안내를 내고 무시. Config를 자동 수정하지 않음 |
| CMake 경로 | configure → MSVC 확인 → build → CTest discovery/0개 거부 → test |
| MSBuild adapter 경로 | build → 명시된 testCommand. FESA의 solution-only 검증을 승인하는 의미가 아님 |

명령은 `shell=False`로 실행하며 repository-relative 설정 경로와 cwd 범위, timeout을 검사한다. 전체 deadline은 현재 1,800초이고 각 명령에는 남은 시간과 명령 timeout 중 짧은 값이 적용된다. 실패 후 후속 단계나 자동 재시도를 실행하지 않는다. Config·preset·실행 파일 자체의 side effect를 sandbox처럼 격리하는 기능은 아니다.

내부 Codex 호출·프롬프트 주입, phase 상태기계, branch/commit/push, 대응 파일명 TDD gate, 등록된 PreToolUse/Stop과 자체 sandbox 승인은 제거되었다. 실제 도구·runtime 권한은 계속 따른다. 기존 phase·hook 기록은 이력으로 남기며 새 runner의 입력이나 필수 정리 대상으로 삼지 않는다.

## 6. 실행 순서와 문서별 완료 확인

### Task 1: 공통 운영 결정과 제품 완료 기준

**Modify:** `docs/ADR.md`, `docs/PRD.md`.

**입력:** AH-01~05, 현재 공통 ADR-012·024~027, GEN-010·012. **결과:** 나머지 문서가 참조할 단일 현행 운영 결정과 완료 기준.

- [ ] ADR-028과 §4의 대체 안내를 작성하고 기존 결정 본문·번호를 보존한다.
- [ ] PRD의 문서 역할, GEN-010·012, 검증·완료 절을 §3대로 수정한다.
- [ ] 새 수치 변경의 독립 검토, 필요한 물리/수치/reference evidence가 여전히 필수인지 확인한다. Release audit는 명시 요청일 때만 수행하도록 맞춘다.
- [ ] 두 문서의 diff를 읽어 운영 이외 제품 요구가 변경되지 않았고, 현재 FESA의 ADR-013에 경량화 신뢰 경계를 덮어쓰지 않았는지 확인한다.

### Task 2: Agent·Skill·Feature 문서 운영

**Modify:** `docs/SOLVER_AGENT_DESIGN.md`, `docs/SOLVER_SKILL_DESIGN.md`, `docs/FEATURE_DOCUMENTATION.md`.

**입력:** Task 1, 현재 profile·SKILL.md. **결과:** 조건부 역할 선택, 최소 인계, 핵심 문서 3개의 일관된 계약.

- [ ] 7개 역할을 호출 조건과 기본 강도로 설명하고 메인의 직접 계획·구현·수정 책임을 명시한다.
- [ ] 고정 stage/envelope/outcome/retry budget을 제거한다. Dispatch는 작업·관련 경로/절·수정 파일·검증 기준, return은 결과·변경 파일·검사 결과·미해결 항목으로 정리한다.
- [ ] 필요한 문서만 읽고 연속 수정은 같은 owner가 수행하도록 정리한다. 지원되는 경우 `fork_turns="none"`을 사용하되 실제 도구·역할 설정이 기준임을 유지한다.
- [ ] PRD checklist·선택적 requirements 및 상세 보고서, 기존 coordination 이력 보존을 세 문서에서 일치시킨다.
- [ ] 기존 numerical/reference/physics 검토의 실질적 내용이 단순 역할 삭제와 함께 사라지지 않았는지 확인한다.

### Task 3: Harness 사용법과 실행 흐름

**Modify:** `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`.

**입력:** Task 1~2, runner/config/discovery/adapter/process, 현재 preset. **결과:** §5와 일치하는 사용법과 영향별 검증 사례.

- [ ] HARNESS에는 설치·설정·정확한 CLI·exit·이전 방식 변경 안내를 둔다. 기존 설정을 무조건 덮어쓰는 복사 안내는 피한다.
- [ ] HARNESS_WORKFLOW는 메인의 개발 흐름과 runner 내부 실행 순서로 재작성한다. 설치/JSON 예시는 HARNESS에 연결하여 중복을 줄인다.
- [ ] 문서만 변경하면 정적 검토, 일반 버그는 재현·관련 검사, 새 수치 기능은 필요한 정식화·독립 검토·구현·물리/reference 검사로 분기하는 표를 작성한다.
- [ ] 도움말·usage·backend 결과는 소스로 대조한다. 문서 갱신 확인을 위해 실제 runner나 pytest를 실행하지 않는다.

### Task 4: 루트 지침·아키텍처·코딩 지침 동기화

**Modify:** `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/CODINGSTYLE.md`.

**입력:** Task 1~3의 현행 계약. **결과:** 다음 작업부터 적용되는 짧고 모순 없는 루트 지침.

- [ ] AGENTS의 운영·Feature 관리·검증 절을 갱신하고 상세 전담 문서에 링크한다. 모든 문서·모든 stage를 매 작업마다 읽으라는 의무를 제거한다.
- [ ] ARCHITECTURE의 개발 흐름과 owner 표를 바꾸고 solver runtime 책임과 물리/수치 계약을 보존한다.
- [ ] CODINGSTYLE의 동작 검증·refactor 예외·전체 검증 시점·담당자 checklist만 수정한다. Doxygen/naming/formatting 요구는 유지한다.
- [ ] “agent profile 제거”와 “해당 전문 skill/검증 제거”를 혼동한 문장이 없는지 확인한다.

### Task 5: 통합 정적 확인과 인계

**Modify:** 앞선 10개 문서의 발견된 모순만 수정한다. 새 자동화·테스트 파일을 추가하지 않는다.

- [ ] AH-01은 AGENTS/AGENT_DESIGN/ARCHITECTURE, AH-02는 HARNESS/WORKFLOW, AH-03은 PRD/CODINGSTYLE, AH-04는 AGENT_DESIGN/SKILL_DESIGN, AH-05는 FEATURE_DOCUMENTATION/PRD에 반영됐는지 확인한다. 공통 근거는 ADR-028로 연결한다.
- [ ] 아래 검색 결과를 현행 규칙, 폐기 안내, 과거 ADR 본문으로 분류한다. 폐기한 기능을 현행 의무로 설명하는 결과가 없어야 한다.
- [ ] 변경 문서의 상대 링크·절 링크·agent/skill 이름·CLI·preset 값을 확인한다. 삭제된 profile/hook 경로는 현재 파일 링크로 두지 않는다.
- [ ] root AGENTS의 byte 크기를 확인한다. 내용을 줄이되 필수 FESA 계약을 제거하여 분량만 맞추지 않는다.
- [ ] 최종 diff가 요청한 10개 문서에 한정되는지 확인하고 기존 사용자 변경은 보존한다. 문서 정합성과 미실행 검사를 구분하여 보고한다.

정적 검색·diff 예시(PowerShell, 저장소 루트):

```powershell
$docTargets = @(
  'AGENTS.md', 'docs/ADR.md', 'docs/ARCHITECTURE.md', 'docs/PRD.md',
  'docs/SOLVER_AGENT_DESIGN.md', 'docs/SOLVER_SKILL_DESIGN.md',
  'docs/HARNESS_WORKFLOW.md', 'docs/HARNESS.md', 'docs/CODINGSTYLE.md',
  'docs/FEATURE_DOCUMENTATION.md'
)
rg -n 'coordinator-agent|implementation-planning-agent|correction-agent|release-agent|xhigh|coordination\.md|owned_paths|attempt_history|retry_key|PreToolUse|Stop|hooks\.json|FEM_HARNESS_CODEX_SANDBOX|approve-danger-full-access|--push|9개|정규 stage' @docTargets
rg -n 'execute\.py|GEN-010|GEN-012|ADR-028|medium|high|reference|TOLERANCE' @docTargets
git diff --check -- $docTargets
git diff --stat -- $docTargets
git diff -- $docTargets
(Get-Item -LiteralPath 'AGENTS.md').Length
```

검색어를 전부 없애는 것이 합격 조건은 아니다. ADR 이력과 명시적인 폐기 안내는 허용하며, solver의 해석 step/state/retry 의미를 개발 phase와 혼동하여 삭제하지 않는다. UTF-8과 기존 개행을 보존하며 링크와 의미는 사람이 함께 확인한다. 자동 문자열·heading 맞춤 테스트를 만들지 않는다.

## 7. 범위 밖 후속 정합성 항목

다음은 현재 파일을 읽어 확인한 불일치다. 테스트를 실행하여 얻은 실패 결과는 아니며, 이번 문서 수정의 코드/테스트 작업으로 편입하지 않는다.

| 파일 | 현재 남아 있는 기대 | 후속 작업의 방향 |
| --- | --- | --- |
| [tests/test_execute.py](../../../tests/test_execute.py), [tests/test_execute_ownership.py](../../../tests/test_execute_ownership.py) | 삭제된 `StepExecutor`, phase·Git·owned_paths·retry 처리 | 별도 구현 작업에서 새 runner의 성공·실패·timeout·Git 무변경 동작에 맞는 coverage로 정리 |
| [tests/test_hook_validation_scope.py](../../../tests/test_hook_validation_scope.py) | 삭제된 `scripts.hooks` import와 Stop 동작 | 폐기된 hook 검사와 유지할 실행기 검증을 구분 |
| [tests/test_agent_skill_workflow_contract.py](../../../tests/test_agent_skill_workflow_contract.py) | 전용 Coordinator, 9단계, `xhigh`, phase 예시 preflight | 실제 7개 profile과 조건부 skill 계약에 맞추되 문구 강제를 새로운 합격 기준으로 만들지 않음 |
| [tests/test_harness_preset_contract.py](../../../tests/test_harness_preset_contract.py) | tracked config 예시가 Ninja preset 필드를 모두 포함한다고 기대 | 간소화된 예시와 FESA 명시 preset 지원을 구분하여 검증 |

문서 10개를 갱신하는 일은 이 불일치의 해결과 별개로 완료할 수 있다. 다만 저장소 전체 Python 검사, 실제 C++ build/test, 수치/reference 검증이 통과했다고 보고할 수는 없다. 이번 계획과 후속 문서 작업에는 이 실행들을 포함하지 않는다.

## 8. AGENTS.md Quality Report

### Summary

- Files found: `AGENTS.md`, `docs2/AGENTS.md`의 2개. 수정·평가 대상은 요청된 루트 파일 1개다.
- Active project chain at `C:/git/FESADev`: `AGENTS.md`. 프로젝트 내 override는 발견되지 않았다.
- `docs2/AGENTS.md`는 별도 subtree에만 적용되는 참고 자료다. 루트 체인에 합산하지 않으며 전역 사용자 지침은 이번 audit 범위 밖이다.
- Average score: **60/100**. Files needing update in scope: **1**.
- Combined selected project-chain size: **24,487 bytes**; 기본 비교 한도 32 KiB 이내다. 전역 지침을 포함한 runtime 실제 주입량을 측정한 값은 아니다.

### File-by-File Assessment

#### 1. AGENTS.md (project root; active)

**Score: 60/100 (Grade: C)**. 점수는 문서 정합성 평가이며 솔버 품질 평가가 아니다.

| Criterion | Score | Evidence |
| --- | ---: | --- |
| Commands and workflows | 10/20 | CMake/CTest 진입점은 남아 있으나 phase CLI·hook·전용 Coordinator workflow는 현재 구현과 다름 |
| Repository map and instruction scope | 15/20 | FESA runtime/Feature 경계는 유효하나 삭제한 profile·hook 경로를 현행 지침으로 참조 |
| Non-obvious constraints and gotchas | 15/15 | Source identity, 수치/물리 검증, reference 무결성, state·HDF5 보존의 구체적 제약 유지 |
| Conciseness and duplication | 5/15 | stage·handoff·retry·hook의 상세 의무를 여러 전담 문서와 중복 유지 |
| Currency against the codebase | 5/15 | 7개 profile·medium/high·인자 없는 runner·hook 삭제를 아직 반영하지 않음 |
| Actionability and verifiability | 10/15 | 검증 명령과 경계는 구체적이나 현재 수행할 수 없는 절차를 의무화 |

**Issues:** 삭제된 운영 기능을 요구하고, 간소화된 skill보다 더 강한 상태기계·파일명 TDD·전체 검증 반복을 지시한다.

**Recommended changes:** §3의 AGENTS 수정 범위만 반영한다. 상세 기술·수치 규칙은 유지하고 전담 문서와의 중복 운영 설명을 줄인다.

### Update: AGENTS.md

**Why:** AH-01~05와 실제 profile/runner/skill에 맞게 현행 지침을 바꾼다. 아래는 핵심 문구의 제안 diff이며 전체 적용 범위는 §3·Task 4를 따른다. 이 계획 작성 중에는 적용하지 않는다.

```diff
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
+ 동작 추가·수정은 해당 동작을 확인하는 테스트로 검증한다. 버그는 가능한 경우 실패를 재현한 뒤 최소 수정한다.
+ 기존 coverage가 충분한 rename·refactor나 문서 수정에는 형식적인 새 테스트를 요구하지 않는다.
```

```diff
- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
+ 일반 specialist의 기본 추론 강도는 `medium`, 정식화·수치·물리 검토는 `high`다. 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
```

```diff
- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다.
+ 메인 assistant가 범위를 파악하고 필요한 전문 작업만 위임하며 구현·검증·결과 확인을 조정한다.
+ 수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 필요한 analytical/invariant·reference 검증은 유지한다.
+ 변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 필수 reference 비교를 한 번 수행한다. 이후 변경·실패가 없으면 반복하지 않는다.
```

```diff
- python scripts/execute.py <phase-dir>
+ python scripts/execute.py
```

새 CLI 한 줄 교체만으로 완료하지 않는다. 기존 phase 인자·push·sandbox·hook 설명을 §5에 맞게 함께 갱신하고, 관리 문서 표에서 신규 `coordination.md` 요구를 제거하여 PRD checklist로 연결한다.

## 9. 최종 산출물과 완료 기준

- 요청된 문서 10개의 검토 가능한 diff와 ADR-028의 명확한 대체 관계.
- 현재 역할·skill·CLI·설정·검증 시점이 일치하고 폐기 기능을 현행 필수 절차로 요구하지 않음.
- FESA 제품·수치·입출력·코딩 계약과 필요한 독립 검증이 보존됨.
- 상대 링크·소스 대조·diff/공백 검사를 정적으로 확인하고, 과거 evidence와 현재 미실행 항목을 구분해 보고함.
- 사용자 구현 변경·테스트·개인 설정·기존 phase/Feature 이력은 보존됨. 저장소 전체 검증 완료나 commit/push 완료로 확대하여 보고하지 않음.