30 KiB

Raw Blame History

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, AH-01~05 결정, 승인 계획 보존본, 기존 구현 보고서.

작성일: 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, reference artifact와 solver 구현은 수정 대상이 아니다. 수치 검토와 필요한 analytical/invariant·reference 검증을 유지한다.
운영 간소화를 이유로 물리 의미, 공개 schema, 지원 범위, tolerance, 외부 실행·원격·파괴 작업 권한을 확대하지 않는다.
작은 문서 작업에는 solver Feature 폴더·관리 문서·stage 보고서를 새로 만들지 않는다. 이 계획도 별도 solver Feature workflow를 시작하지 않는다.
문서만 갱신하므로 새 테스트, pytest, Harness, CMake/CTest, 수동 hook을 실행하지 않는다. 확인 범위는 문서·링크·설정·소스의 정적 대조다.
기존 문서의 언어·구성을 가능한 한 유지한다. 문서 전체 복사나 요청과 무관한 코딩 규약 정리는 하지 않는다.

근거의 적용 순서

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

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

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

근거	확인한 내용	문서 반영 판단
현재 profiles	7개 specialist만 남고 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`다. Implementation profile의 모델은 `gpt-5.6-terra`다.	삭제된 4개 전용 역할과 일괄 `xhigh` 요구를 제거한다. 모델 선택은 profile로 연결하고 runtime 적용을 검증했다고 주장하지 않는다.
runner, harness skill	인자 없는 명시적 검증 실행기다. 내부 LLM, phase 상태 처리, 자동 Git·retry가 없다.	새 CLI와 현재 exit 의미를 설명한다. 옛 CLI는 폐기 안내에서만 보여 준다.
config, discovery	legacy `tdd`는 설정 로드 시 안내 후 무시한다. C++ 전체 scan과 orphan-C++ gate가 없다.	현재 없는 TDD pattern 설정·C++ 파일 scan·자동 skip 설명을 삭제한다.
config 예시, presets	예시는 `projectType=cmake`, `sourceDir=.`만 지정한다. FESA Ninja preset은 별도로 존재한다.	예시 복사만으로 Ninja preset을 선택한다고 쓰지 않는다. 명시적 preset 설정 예시를 유지한다.
`docs2`의 PRD·ARCHITECTURE·구현 보고서	solver/build metadata가 없는 framework checkout을 전제로 한다.	현재 CMakeLists, solver target, test target이 있으므로 해당 현황 설명은 옮기지 않는다.
`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	`문서 기준과 Feature 관리`, `개발 운영 인프라`, `개발 프로세스`, `Agent/Skill Workflow`, `최소 검증 진입점`을 갱신한다. 메인 직접 조정, 조건부 specialist, 핵심 문서 3개·PRD checklist, 간결한 인계, 명시적 검증을 요약한다. 소유권 절의 매 변경 RED·대응 C++ test 강제를 동작 중심 검증으로 바꾸고, reference 변경 권한의 “요청된 phase”를 “명시적으로 요청된 작업 범위”로 고친다.	제품 정체성, FESA 기술 스택, 수치·선형 정적 불변식, reference 무결성, 사용자 변경 보존을 유지한다. 상세 CLI·workflow를 중복 복사하지 않고 전담 문서에 연결한다.
docs/ADR.md	ADR-028을 추가하고 ADR-012·024~027에 대체/부분 대체 안내를 붙인다. 머리말의 현행 운영 ADR 범위와 ADR-001·002 등의 현행 운영 참조를 확인한다.	기존 ID와 결정 본문을 소급 재작성하지 않는다. 실제 ADR-013 및 다른 solver 결정은 변경하지 않는다. §4의 대체 범위를 사용한다.
docs/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	문서 역할 표의 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	고정 stage·Coordinator 전용 전이·12필드 envelope·5개 outcome 강제·correction signature/budget을 제거한다. 메인의 작업 선택, 7개 specialist 호출 조건/수정 경계/기본 강도, 간단한 dispatch·return, 구현 owner의 실패 수정, 완료 evidence와 사용자 결정 경계를 정의한다.	새 수식·요소·재료·적분·상태 갱신의 독립 numerical review를 유지한다. 상위 계약 문제의 owner 반환, 무근거 반복 금지, specialist의 범위 제한을 유지한다.
docs/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	요구사항→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 실행의 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	`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가 필요한 조건과 메인 소유 핵심 문서 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 설명에 넣을 정확한 계약

명령과 설정

python scripts/execute.py

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

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

{
  "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, 저장소 루트):

$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_ownership.py	삭제된 `StepExecutor`, phase·Git·owned_paths·retry 처리	별도 구현 작업에서 새 runner의 성공·실패·timeout·Git 무변경 동작에 맞는 coverage로 정리
tests/test_hook_validation_scope.py	삭제된 `scripts.hooks` import와 Stop 동작	폐기된 hook 검사와 유지할 실행기 검증을 구분
tests/test_agent_skill_workflow_contract.py	전용 Coordinator, 9단계, `xhigh`, phase 예시 preflight	실제 7개 profile과 조건부 skill 계약에 맞추되 문구 강제를 새로운 합격 기준으로 만들지 않음
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를 따른다. 이 계획 작성 중에는 적용하지 않는다.

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

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

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

- 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 완료로 확대하여 보고하지 않음.

30 KiB Raw Blame History