From 5e2a30fce06eba5e7ba4fda670328462c7a0cd02 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Mon, 7 Sep 2026 22:12:48 +0900 Subject: [PATCH] docs: align guidance with simplified agent and harness workflow --- AGENTS.md | 133 +++--- docs/ADR.md | 70 +++- docs/ARCHITECTURE.md | 72 ++-- docs/CODINGSTYLE.md | 22 +- docs/FEATURE_DOCUMENTATION.md | 125 +++--- docs/HARNESS.md | 208 +++++----- docs/HARNESS_WORKFLOW.md | 744 ++++------------------------------ docs/PRD.md | 35 +- docs/SOLVER_AGENT_DESIGN.md | 279 +++++-------- docs/SOLVER_SKILL_DESIGN.md | 209 ++++------ 10 files changed, 593 insertions(+), 1304 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3b02cfb..8c55ca5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ - FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다. - 새 기능은 입력 keyword만 인식하거나 element kernel만 존재한다고 완성된 것이 아니다. Semantic model, equation system, 해법, 결과 복구, HDF5 외부 계약과 독립 검증 evidence가 하나의 추적 가능한 기능을 이뤄야 한다. -- 설계나 구현 전에 [PRD](docs/PRD.md)의 제품 범위, [ARCHITECTURE](docs/ARCHITECTURE.md)의 소유권과 데이터 흐름, [ADR](docs/ADR.md)의 기존 결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다. +- 설계·구현 전에 [PRD](docs/PRD.md), [ARCHITECTURE](docs/ARCHITECTURE.md), [ADR](docs/ADR.md)에서 현재 작업에 관련된 제품 범위·소유권·데이터 흐름·결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다. 같은 문맥에서 읽은 변경 없는 자료를 다시 읽지 않는다. - 재사용 가능한 agent, skill과 Harness는 개발 운영 인프라다. 이를 일반화해도 이 저장소가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 승인된 수치 계약은 바뀌지 않는다. - FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라 Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을 @@ -40,24 +40,24 @@ ## 문서 기준과 Feature 관리 -- 공통 역할·handoff·상태 전이·재시도는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 구성과 적용 경계는 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), Feature 문서 배치와 소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 기준으로 한다. 실제 skill 실행 절차는 해당 `SKILL.md`를 읽는다. -- [HARNESS](docs/HARNESS.md)와 [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 설치·흐름 참고 문서다. 승인·역할·상태 전이는 위 agent 계약과 현재 [harness skill](.agents/skills/harness/SKILL.md), 실행 메커니즘은 선택된 설정과 현재 `scripts/` 구현에 대조한다. 오래된 설명으로 이 계약을 덮어쓰지 않으며, 구현이 승인된 제품·수치 계약을 바꿀 권한도 없다. -- 기능별 승인 계약과 모든 agent 보고서는 `docs//`에 둔다. Coordinator가 안정적인 kebab-case Feature ID를 정하고 모든 dispatch에서 같은 폴더와 revision을 사용한다. 기존 `docs/features//` 자료가 있으면 자동 이동·복제하지 않고 필요한 경로와 revision을 참조한다. -- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크나 결정을 루트 문서에 누적하지 않는다. 프로젝트 공통 지침 수정은 별도 사용자 요청으로 승인된 범위에서만 수행한다. -- Coordinator는 새 Feature에 아래 관리 문서를 실제 요구사항으로 초기화한다. 재개 시 기존 기록을 읽고 필요한 부분만 갱신하며, 승인되지 않은 내용을 승인으로 표시하거나 후속 stage의 빈 보고서를 미리 만들지 않는다. +- 현행 운영 결정은 [ADR-028](docs/ADR.md#adr-028), 역할·인계·실패 처리는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 적용은 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), 문서 배치·소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 따른다. 실제 절차는 필요한 `SKILL.md`와 관련 reference만 읽는다. +- [HARNESS](docs/HARNESS.md)는 설치·설정·CLI, [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 개발·검증 흐름을 설명한다. 실행 동작은 선택된 설정과 현재 `scripts/`에 대조하며 구현이 승인된 제품·수치 계약을 바꿀 권한은 없다. +- 지속할 계약·evidence가 필요한 Feature는 메인이 안정적인 kebab-case ID와 `docs//`를 정한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다. +- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크를 누적하지 않으며 공통 지침 수정은 별도 사용자 요청 범위에서 수행한다. +- 새 Feature를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다. 각 문서는 프로젝트 AGENTS·PRD·ADR를 상대 Markdown 링크로 참조한다. -| Coordinator 소유 문서 | 내용과 경계 | +| 메인 소유 문서 | 내용과 경계 | | --- | --- | -| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 산출물 경로·owner·revision·검토 상태 목록, 현재 상태 문서 링크 | -| `PRD.md` | 사용자 요구, 범위·제외, acceptance 요약과 requirement ID별 계약 링크. 요구사항·검증 matrix 원본은 Requirement Agent의 `requirements.md` | -| `ADR.md` | Feature 결정 ID·상태·이유·영향, 결정 owner와 승인 근거 링크 | -| `coordination.md` | stage·outcome·next owner·contract revision, gate evidence·retry·blocker·다음 작업의 유일한 workflow 상태 원본 | +| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당 owner와 문서 목록. 현재 checklist는 PRD로 연결 | +| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본이며 복잡한 상세 계약은 필요한 경우만 분리하여 연결 | +| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거 | -- 관리 문서에서 실제 프로젝트 기준 문서를 상대 Markdown 링크로 연결한다. Coordinator의 목록·참조·상태 관리는 specialist 본문을 대신 작성·수정할 권한이 아니다. -- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 모든 dispatch와 Harness step의 필수 입력에 Feature 폴더 및 그 안의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md` 경로를 명시한다. -- 기본 보고서는 Feature ID·owner·입력 revision, 핵심 결과, evidence, 미해결 항목·handoff만 간결하게 기록한다. 긴 유도·schema·상세 분석은 같은 폴더의 `formulation-derivation.md`, `io-schema.md` 같은 상세 문서로 분리하고 상대 링크로 연결한다. 본문과 상세 문서에 같은 내용을 중복 유지하지 않는다. -- 상세 문서는 기본 산출물과 동일 owner·Feature ID·입력 revision을 사용하며 같은 stale 판정을 받는다. 반환 `evidence_paths`에는 기본 문서와 작성·갱신하거나 판정에 사용한 상세 문서를 포함한다. Coordinator는 실제 파일과 링크를 확인하고 목록에 등록한다. -- 소스·테스트·Harness 제어 파일·기계 생성 로그/결과·read-only reference artifact는 각각의 지정 경로에 유지하고 보고서에서 참조한다. 필수 검증을 생략했다면 미실행 사실과 이유를 남긴다. +- 현재 checklist는 PRD 한 곳에 둔다. `requirements.md`·검증 matrix는 분리가 필요할 때만 작성하고 PRD에는 요약·링크만 유지한다. Specialist는 할당된 전문 문서만 수정한다. +- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 메인은 필요한 Feature context와 관련 경로·절만 인계하며 모든 문서를 매번 재독하도록 요구하지 않는다. +- 기존 `coordination.md`, `docs/features//`와 phase 자료는 이력으로 보존하고 필요한 경로·계약 revision을 참조한다. 자동 이동·복제하거나 신규 coordination 상태 파일을 만들지 않는다. +- 보고서는 결정·결과, 적용 계약, evidence와 미해결 항목을 간결하게 기록한다. 간단한 구현·build/test·reference 결과는 한 보고서로 모으고 긴 유도·schema는 같은 폴더의 상세 문서로 분리해 연결한다. +- 실제 계약 변경은 관련 evidence의 유효성을 다시 확인한다. 의미 변화 없는 문서 편집마다 고정 handoff·hash·gate 기록을 만들지 않는다. 미실행 검사는 이유를 남기며 승인·통과로 표시하지 않는다. +- 소스·테스트·기계 생성 로그/결과·read-only reference artifact는 지정 경로에 유지하고 보고서에서 참조한다. ## FESA 개발의 핵심 원칙 @@ -72,9 +72,9 @@ ### 소유권과 의존성 - CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다. -- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다. -- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다. -- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다. +- 동작 추가·수정은 해당 동작을 확인하는 테스트로 검증한다. 버그는 가능한 경우 실패를 재현한 뒤 최소 수정한다. +- 기존 coverage가 충분한 rename·refactor나 문서 수정에는 형식적인 새 테스트를 요구하지 않는다. +- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 작업 범위에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다. - CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다. - CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다. - Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다. @@ -95,17 +95,11 @@ ### 개발 운영 인프라 -- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다. -- Harness runner는 [scripts/execute.py](scripts/execute.py)이며 `feat-` branch prefix를 사용한다. 실행 전 Git top-level이 Harness root와 같아야 하고, 선택된 phase 제어 파일 allowlist 밖의 worktree는 clean이어야 한다. 관련 없는 변경을 stage하거나 숨기지 않는다. -- Executor는 branch, 현재 pending step 선택, transport attempt, timestamp, path-scoped staging/commit과 phase 진행을 소유한다. 구현 경로와 phase metadata를 분리해 commit하며 저장소 전체를 무조건 stage하지 않는다. Implementation Agent는 선택된 step의 코드·테스트·보고서와 result payload만 갱신하며 branch/commit/push나 다른 step·제어 metadata를 변경하지 않는다. -- Planning은 각 Step의 승인된 정확한 상대 파일 목록을 phase index의 `owned_paths`에 기록한다. 모든 pending Step은 실행 전에 목록이 필요하고 `[]`는 구현 파일 변경 없음을 뜻한다. Executor는 신뢰된 목록으로 매 시도 후·stage 전·commit 전 경로를 검사하며 rename 양쪽 경로도 승인되어야 한다. 범위 밖 변경은 보존하고 재시도·커밋·다음 Step 진행을 중단한다. 실행 중 동시 편집까지 원자적으로 격리하는 보장은 아니다. -- Executor의 process/session transport 시도는 실제 wrapper timeout과 결과 미보고가 확인된 경우에만 최초 포함 최대 2회이며 Coordinator의 correction budget과 별개다. 비정상 종료에서도 명시적 `error/blocked`를 보존하고, 인식된 sandbox helper 환경 실패는 종료 코드 0에서도 `blocked`로 기록한다. Executor 소유 `attempt_history`는 재시도·재개 때 보존하며 구현·상위 계약·환경·물리 실패를 transport retry로 반복하지 않는다. -- 기본 sandbox는 `FEM_HARNESS_CODEX_SANDBOX=workspace-write`다. `danger-full-access`는 동일 명령의 native sandbox 실패 증거, 해당 실행 직전 사용자의 명시적 승인, clean linked Git worktree와 `--approve-danger-full-access`가 모두 필요하다. 환경변수 설정만으로 승인되지 않는다. `--push` 등 원격 작업도 별도 명시적 승인이 필요하다. -- Hook 연결은 [.codex/hooks.json](.codex/hooks.json), 구현은 [scripts/hooks](scripts/hooks)와 [scripts/msvc_harness](scripts/msvc_harness)에 둔다. Hook script를 수동 실행해 등록된 hook이나 검증 evidence를 대체하지 않는다. -- PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하고 허용된 편집 경로를 기록한다. 이는 RED 실행이나 correctness의 증거가 아니다. -- Stop은 유효한 동일 session/turn 기록에서 기록된 편집 도구의 대상이 모두 저장소 내부 `.md`일 때 build/test를 생략한다. 기록 누락·손상 또는 비문서 변경이면 정상 검증 경로를 따른다. Shell 쓰기는 이 기록이 완전히 추적하지 못하며, 편집 기록 없는 읽기 전용 계획 요청도 자동 생략을 보장하지 않는다. -- 생략하지 않는 Stop은 `.harness/config.json` 또는 자동 감지 결과의 backend로 build/test를 검증한다. 문서 작업에서 사용자가 실행을 제외하면 수동으로 Hook·CMake·CTest 등을 실행하지 않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작하거나 생략된 검증을 통과로 보고하지 않는다. -- `.harness/hook-state/`와 `phases/**/step*-output.json` 같은 생성 실행 기록은 ignored 상태로 유지한다. +- 일반 specialist의 기본 추론 강도는 `medium`, 정식화·수치·물리 검토는 `high`다. 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따르고 난해한 작업에만 필요한 범위에서 높인다. +- [scripts/execute.py](scripts/execute.py)는 명시적 build/test 실행기다. 내부 LLM·phase 상태기계·자동 Git·재시도·파일명 TDD gate·대화 종료 hook을 사용하지 않는다. +- 설정·preset·명령은 검토할 실행 입력이다. `shell=False`·경로 검사·timeout이 모든 side effect를 격리하는 sandbox는 아니며 실제 도구 권한과 외부 실행 승인은 별도로 따른다. +- 관련 없는 사용자 변경은 보존한다. Commit을 요청받으면 작업 경로만 stage하고 push·tag·publish 등 원격 작업은 명시적으로 승인된 범위에서 수행한다. Runner는 이 권한을 부여하거나 Git 상태를 변경하지 않는다. +- 기존 phase·hook 생성 기록은 이력으로 보존하며 ignored 상태를 유지한다. 현재 검증을 위해 기록을 조작하거나 삭제된 hook을 수동 실행하지 않는다. ## 기능을 추가할 때의 판단 기준 @@ -118,62 +112,60 @@ ## 개발 프로세스 -- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다. +- 동작 변경을 검증하는 테스트와 가능한 버그 재현을 기본으로 하며 최소 수정 후 관련 검사를 수행한다. - CRITICAL: 빌드 경고를 새로 추가하지 말 것. -- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다. 문서 수정·읽기 전용 검토를 새 solver feature 전체 workflow로 확대하지 않는다. -- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, outcome, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID의 기본 형식은 `FEM-REQ--###`이다. +- 수식·요소·재료·적분·상태 갱신 변경은 독립 numerical review와 해당 analytical/invariant 검증을 수행한다. 필요한 물리·reference 검증도 유지한다. +- 변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 필수 reference 비교를 한 번 수행한다. 사용자 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하며 이후 변경·실패가 없으면 반복하지 않는다. +- 문서만 수정하는 작업은 링크·소스 대조·diff 정적 검토로 확인하고 build/test를 실행하지 않는다. 미실행을 통과로 보고하지 않는다. +- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ--###`이다. - 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`. ## Agent/Skill Workflow -Solver feature workflow에서 `coordinator-agent`만 main agent로서 상태 전이와 closure를 -소유하며 다음 eligible specialist에게 한 번에 하나의 bounded task를 dispatch한다. -Specialist는 peer를 호출하거나 다음 gate로 진행하거나 자신의 산출물을 최종 승인하지 않는다. -Intake/coordination은 아래 정규 stage와 별도로 관리한다. +메인 assistant가 범위를 파악하고 필요한 전문 작업만 위임하며 계획·구현·검증·결과 확인을 +조정한다. 작은 작업은 직접 수행하고 고정된 stage 순회나 별도 coordinator를 호출하지 않는다. -| 단계 | 담당 sub-agent | 필수 skill | 기본 보고서 (`docs//`) | -| --- | --- | --- | --- | -| 1. `requirements` | `requirement-agent` | `fem-requirements-baseline` | `requirements.md` | -| 2. `research` | `research-agent` | `fem-research-evidence` | `research.md` | -| 3. `formulation` | `formulation-agent` | `fem-formulation-spec` | `formulation.md` | -| 4. `numerical-review` | `numerical-review-agent` | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` | -| 5. `io-definition` | `io-definition-agent` | `fem-io-contract` | `io.md` | -| 6. `implementation-planning` | `implementation-planning-agent` | `fem-implementation-tdd`, `harness` | `implementation-plan.md` | -| 7. `implementation` | `implementation-agent` | `fem-implementation-tdd` | `implementation-report.md`, `build-test.md`, `reference-comparison.md` | -| 8. `physics-evaluation` | `physics-evaluation-agent` | `fem-physics-review` | `physics-evaluation.md` | -| 9. `release-readiness` | `release-agent` | `fem-release-readiness` | `release.md` | +| Specialist | 호출 조건 | Skill | +| --- | --- | --- | +| `requirement-agent` | 복잡하거나 상충하는 scope·acceptance 정리 | `fem-requirements-baseline` | +| `research-agent` | 부족한 이론·benchmark·reference 근거 조사 | `fem-research-evidence` | +| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화 | `fem-formulation-spec` | +| `numerical-review-agent` | 정식화·주요 수치 변경·수치 불일치의 독립 검토 | `fem-numerical-review` | +| `io-definition-agent` | 입력 의미·진단·결과 schema·비교 mapping 정의 | `fem-io-contract` | +| `implementation-agent` | 위임할 이점이 있는 구현 묶음 | `fem-implementation-tdd` | +| `physics-evaluation-agent` | 평형·물리 타당성·coverage 평가 | `fem-physics-review` | -- 위 8개 lifecycle skill은 [.codex/skills](.codex/skills)에 있다. Planning은 할당된 `phases/index.json`, `phases//index.json`, `stepN.md`도 소유하고, Implementation은 할당된 코드·테스트·build registration을 소유한다. -- 보조 skill은 [.agents/skills/harness](.agents/skills/harness/SKILL.md)의 phase 계획·실행, [.agents/skills/review](.agents/skills/review/SKILL.md)의 읽기 전용 diff 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)의 configured FEM wiki 근거·coverage gap 조회다. `fem-theory-query`를 모든 FEM 질문에 적용하거나 workstation vault 절대 경로를 commit하지 않는다. -- 모든 dispatch/return은 SOLVER_AGENT_DESIGN의 공통 envelope를 사용한다. Workflow outcome은 `pass | return-upstream | retry | blocked-environment | needs-user-decision`만 사용한다. Specialist outcome은 전이 요청이며 Coordinator가 실제 산출물·owner·revision·evidence를 확인한 뒤 상태를 기록한다. -- `return-upstream`은 정확한 계약 owner로 반환하고 영향받는 downstream evidence를 stale 처리한다. Numerical Review는 formulation과 reference-model readiness, Implementation은 TDD·전체 build/test·필수 reference comparison 증거가 모두 있어야 통과한다. Release의 `pass`는 내부 readiness일 뿐 push/tag/publish/deploy/package 권한이 아니다. -- `correction-agent`는 정규 stage가 아닌 on-demand rework다. Coordinator는 `retry_key = feature_id|failing_gate|normalized_failure_classification|contract_revision`별 correction을 최대 한 번 허용하고 이후 Implementation rerun을 한 번 dispatch한다. 같은 key가 다시 실패하면 두 번째 correction을 금지하고 계약·환경·critical decision owner로 반환한다. 문구만 바꿔 key를 새로 만들지 않으며 `corrections.md`는 실제 correction 때만 작성한다. -- 승인된 Feature와 할당된 dispatch 안의 일반 문서·계획 파일 작성 및 bounded local 실행에는 반복적인 사용자 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않으며 Harness 실행은 해당 작업에 실행까지 할당된 경우에만 한다. -- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명, 보안·법률 위험 수용, destructive/remote/release 작업은 SOLVER_AGENT_DESIGN의 critical decision 절차를 따른다. 권한이 필요한 실행을 일반 자율 작업으로 확대하지 않는다. -- Harness step은 0부터 연속 번호로 나누고 각 step 안에서 `RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY`를 완료하도록 계획한다. 정확한 입력·소유 파일·명령·제외 범위·중단 조건을 명시하며 필요한 물리·schema·tolerance·reference가 없으면 해당 owner로 반환한다. -- Harness step 상태 `pending/completed/error/blocked`는 workflow outcome과 별개다. Implementation은 선택된 step에 `completed`와 비어 있지 않은 `summary`, `error`와 `error_message`, 또는 `blocked`와 `blocked_reason`을 반환한다. Executor가 timestamp와 phase 진행을 관리하며 실패 증거를 지우고 즉시 재실행하지 않는다. +- 메인도 `fem-implementation-tdd`로 계획·구현·일반 실패 수정을 수행할 수 있다. 전용 planning/correction profile이나 phase 파일을 요구하지 않는다. +- `fem-release-readiness`는 사용자가 별도 감사를 명시 요청할 때만 사용한다. Readiness 권고는 외부 release 권한이 아니다. +- [harness](.agents/skills/harness/SKILL.md)는 구성된 build/test의 명시 실행, [review](.agents/skills/review/SKILL.md)는 요청 diff의 읽기 전용 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)는 configured FEM wiki 근거·coverage gap 조회에 사용한다. Workstation vault 절대 경로를 commit하지 않는다. +- Dispatch는 작업·관련 경로/절·수정 파일·검증 기준, return은 결과·변경 파일·검사 결과·미해결 항목으로 충분하다. 지원되는 도구에서는 `fork_turns="none"`으로 필요한 문맥만 전달하고 연속 수정은 같은 owner에게 보낸다. +- Specialist는 할당 범위를 지키고 peer를 재위임하거나 상위 계약을 결과에 맞춰 수정하지 않는다. 계약 문제는 owner·경로·근거와 함께 메인에 전달한다. 독립 검토를 자기 승인으로 대체하지 않는다. +- 일반 실패는 현재 구현 owner가 수정한다. 새 근거·변경 없이 같은 명령·agent 호출을 반복하지 않으며 고정 correction/transport 예산을 두지 않는다. +- 승인된 범위의 일반 작업과 인계에 반복 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않는다. +- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명·비용, 중대한 보안·법률 위험, destructive/remote/release 작업은 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md)의 사용자 결정 경계를 따른다. ## 최소 검증 진입점 -아래 명령은 해당 구현·검증 작업에만 사용한다. 문서만 수정하는 작업의 정적 검토를 위해 -build/test를 실행하지 않는다. 실행할 명령은 승인된 step/plan에서 확인하고, -`.harness/config.json`, preset·project metadata와 프로젝트 지침에 대조한 뒤에만 기본값을 -사용한다. Target graph, dependency normalization과 Windows runtime staging은 -ARCHITECTURE와 실제 CMake 파일을 따른다. +아래 명령은 해당 구현·검증 작업에만 사용한다. 현재 작업, `.harness/config.json`, +preset·project metadata와 프로젝트 기준을 대조하여 선택한다. 문서 수정에는 실행하지 않는다. ### Harness Python 검증 +Harness 구현 변경에 필요한 검사는 관련 범위부터 실행하며 전체 검사가 필요할 때는 다음을 사용한다. + ```powershell uv run --with pytest python -B -m pytest -v -rs ``` -### Phase 실행 +### 구성된 전체 build/test ```powershell -python scripts/execute.py +python scripts/execute.py ``` -``는 할당된 phase로 대체한다. `--push`는 원격 push가 명시적으로 승인된 경우에만 추가한다. +Phase 인자나 `--push`·`--approve-danger-full-access`를 추가하지 않는다. 이 인자들은 +usage error로 거부된다. Exit 의미·설정·이전 방식 변경 안내는 [HARNESS](docs/HARNESS.md)를 +따른다. 필요한 수치/reference 검증을 runner 성공만으로 대체하지 않는다. ### CMake/CTest 프로젝트 @@ -189,7 +181,10 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1 ctest --preset windows-msvc-ninja-debug --output-on-failure ``` -Hook도 이 preset을 사용하게 구성하려면 [.harness/config.example.json](.harness/config.example.json)을 -참고해 local `.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을 -함께 맞춘다. Preset 파일이 있다는 사실만으로 Stop이 해당 preset을 선택하지는 않는다. -FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 기준으로 한다. +Runner에도 이 preset을 적용하려면 [HARNESS](docs/HARNESS.md)의 예시에 따라 개인 +`.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을 +함께 맞춘다. 현재 [.harness/config.example.json](.harness/config.example.json)은 최소 +CMake 설정이며 preset 필드가 없다. Preset 파일이 있다는 사실만으로 runner가 이를 +선택하지 않는다. FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 +기준으로 한다. Target graph·dependency·Windows runtime staging은 ARCHITECTURE와 실제 +CMake 파일을 따른다. diff --git a/docs/ADR.md b/docs/ADR.md index 6382413..dae8bfe 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -23,8 +23,9 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한 - 현재 선택된 toolchain, 외부 형식과 구현별 계약은 [AGENTS.md](../AGENTS.md) 및 승인된 설정·Feature 계약을 따른다. 문서 일반화만으로 이를 교체하지 않는다. - 기존 결정 번호는 다른 의미로 재사용하지 않는다. 후속 결정은 마지막 번호 다음으로 추가한다. -- ADR-024~027은 현재 agent·skill·Feature 문서 운영 계약을 기록한다. 새 해석 기능이나 - 외부 실행 권한을 승인하는 결정이 아니다. +- ADR-024~027은 당시 agent·skill·Feature 문서 운영 계약의 이력이다. 현행 운영은 + [ADR-028](#adr-028)을 따른다. 대체 안내 아래의 기존 결정 본문과 그 안의 링크는 + 결정 당시 설명으로 읽으며 현행 절차를 요구하는 근거로 사용하지 않는다. ## 프로젝트 공통 결정 @@ -36,7 +37,7 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한 **이유**: 개발 자동화의 편의가 물리적 의미, 사용자 요구와 수치 검증을 대신하지 않게 한다. **트레이드오프**: Solver의 완료 evidence와 자동화 자체의 correctness를 별도로 관리해야 한다. -현재 운영 역할과 검증 범위는 ADR-024·026에서 보완한다. +현재 운영 역할과 검증 범위는 ADR-028을 따른다. ### ADR-002: 구현·검증 환경은 명시된 프로젝트 baseline으로 관리한다 @@ -47,7 +48,7 @@ backend를 처리할 수 있다는 사실을 FESA 제품 지원으로 간주하 **이유**: 개발 환경의 암묵적 차이가 build와 numerical regression 판정을 흐리지 않게 한다. **트레이드오프**: 새 환경은 별도의 compatibility와 실행 evidence가 필요하다. 원문의 -기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-026의 구성 경계를 따른다. +기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-028이 유지하는 구성 경계를 따른다. ### ADR-003: 외부 입력은 승인된 subset의 의미로 지원한다 @@ -133,6 +134,9 @@ pattern·scatter와 deterministic reduction을 사용한다. ### ADR-012: 계획, 실행과 Hook 검증의 책임을 분리한다 +> **부분 대체 — ADR-028:** 전용 Planning/Executor/Hook 분업은 폐기한다. 실제 검증 +> evidence와 테스트 파일 존재의 구분은 유지한다. 아래 본문은 당시 결정의 이력이다. + **결정**: Planning은 할당된 계획 파일, Executor는 실행 상태와 Git 처리, Hook은 등록된 guardrail과 종료 검증을 담당한다. 테스트 파일 존재는 RED 관찰의 증거가 아니다. @@ -245,6 +249,9 @@ ADR-014·020의 과거 수치 정책을 대체하지만 artifact 선택·identit ### ADR-024: Coordinator가 evidence 기반 workflow와 유한 correction을 소유한다 +> **부분 대체 — ADR-028:** 전용 Coordinator·고정 상태 전이·correction/rerun 예산을 +> 폐기한다. 승인 범위의 자율 작업, 필요한 사용자 결정과 필수 evidence는 유지한다. + **상태**: 현재 [agent 운영 계약](SOLVER_AGENT_DESIGN.md)의 기록. ADR-012의 계획·실행·검증 계층을 보완하며 specialist의 계약 소유권을 변경하지 않는다. @@ -264,6 +271,9 @@ Release readiness가 외부 게시나 배포 권한을 주지는 않는다. ### ADR-025: 프로젝트 기준과 Feature 문서의 원본·소유권을 분리한다 +> **부분 대체 — ADR-028:** 관리 문서 4개·coordination 상태 원본·필수 requirements +> 분리·전체 bundle 인계를 폐기한다. 프로젝트/Feature 경계, 전문 소유권과 원본 구분은 유지한다. + **상태**: 현재 [Feature 문서 관리](FEATURE_DOCUMENTATION.md) 계약의 기록. **결정**: 프로젝트 PRD·ARCHITECTURE·ADR에는 공통 기준만 둔다. Coordinator는 @@ -283,6 +293,9 @@ upstream 변경의 영향과 stale evidence를 추적할 수 있다. ### ADR-026: Harness의 구성, Git 소유권과 검증 범위를 신뢰 경계로 관리한다 +> **부분 대체 — ADR-028:** Executor의 자동 Git·transport·자체 sandbox 통제와 hook +> 검증을 폐기한다. Config/command 신뢰 경계, 사용자 변경 보존과 실제 runtime 권한은 유지한다. + **상태**: 현재 [Harness skill](../.agents/skills/harness/SKILL.md)과 [프로젝트 지침](../AGENTS.md)의 실행 계약 기록. ADR-002의 구체적 실행 구성과 ADR-012의 운영 설명을 보완한다. @@ -312,6 +325,9 @@ PreToolUse의 파일 존재 검사는 RED evidence가 아니다. Stop의 문서 ### ADR-027: Harness의 Step 결과와 커밋 범위를 명시적 계약으로 검증한다 +> **실행 계약 대체 — ADR-028:** phase Step payload·owned_paths·attempt_history·자동 +> commit·transport retry는 더 이상 사용하지 않는다. 실패 증거와 사용자 변경 보존은 유지한다. + **상태**: 사용자 승인된 Harness 보완 계획(실패 상태 보존, 파일 소유권 검증, 환경 오류 분류)에 따른 결정. ADR-026의 실행 경계를 보완하며 solver·Hook·sandbox 권한을 변경하지 않는다. @@ -334,6 +350,52 @@ Planning은 Step마다 정확한 상대 파일 목록 `owned_paths`를 작성한 경로 검사는 filesystem sandbox나 동시 writer에 대한 원자적 격리가 아니다. 구현·metadata 커밋도 단일 transaction이 아니므로 뒤쪽 커밋 실패 시 앞선 커밋을 보존하고 오류로 반환한다. + + +### ADR-028: 메인이 필요한 전문 작업을 조정하고 Harness를 명시적 검증 실행기로 사용한다 + +**상태**: Accepted. 2026-09-07 사용자가 승인한 +[문서 갱신 계획](superpowers/plans/2026-09-07-agent-harness-documentation-update.md)에 따라 +Agent·Harness 경량화 결정을 공통 운영 문서에 반영한다. 솔버의 제품·물리·수치·입출력 +계약과 외부 실행 권한은 변경하지 않는다. + +**결정**: + +- 메인 assistant가 작업 분해, 필요한 전문 작업의 위임, 구현 조정과 완료 확인을 맡는다. + 7개 specialist는 필요한 경우에만 호출한다. 고정 stage 순회와 전용 + coordinator/planning/correction/release profile은 사용하지 않는다. +- Harness는 `python scripts/execute.py`로 구성된 build/test를 한 번 명시 실행한다. + 내부 LLM·프롬프트 주입, phase 상태기계, 자동 Git·재시도, 파일명 TDD gate와 대화 종료 + hook은 사용하지 않는다. 기존 phase와 coordination 기록은 이력으로 보존한다. +- 동작 변경은 의미 있는 테스트로 검증하고, 버그는 가능한 경우 재현한 뒤 최소 수정한다. + 개발 중 관련 검사를 수행하며 솔버 기능 완료 시 전체 build/test와 필수 reference 비교를 + 한 번 수행한다. 이후 변경·실패가 없으면 반복하지 않는다. 수식·요소·재료·적분·상태 + 갱신 변경의 독립 수치 검토와 필요한 analytical/invariant·물리 검증은 유지한다. +- 관련 입력 경로/절, 작업·수정 범위와 검증 기준만 인계하고 결과·변경 파일·검사·미해결 + 항목을 간결하게 반환한다. 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`를 + 기본으로 하며 난해한 작업에만 필요한 범위에서 높인다. +- Feature를 초기화하면 메인이 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. + 현재 checklist와 작은 요구사항의 원본은 PRD에 둔다. 필요한 상세 계약·결과만 분리하여 + 연결하고 간단한 구현·build/test·reference evidence는 하나의 보고서에 기록한다. + Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다. + +이 결정은 ADR-012·024~027의 위에 표시한 운영 부분을 대체한다. Config·preset·실행 +command는 검토해야 할 실행 입력이며 `shell=False`나 경로 검사가 그 side effect를 +sandbox처럼 격리하지는 않는다. 사용자 변경·reference를 보존하고 미실행·실패·stale +evidence를 통과로 표시하지 않는 원칙, 실제 도구 권한과 외부 작업의 명시적 승인은 유지한다. + +**이유**: 반복적인 문맥 주입, 역할 전환, 형식적 보고와 중복 검증을 줄이면서 필요한 +공학적 판단과 재현 가능한 evidence에 집중한다. + +**트레이드오프**: 고정 상태기계나 자동 Git gate가 완료·변경 범위를 강제하지 않으므로 +메인이 할당 범위, 필요한 검증과 미해결 항목을 확인한다. 명령 실패의 원인은 현재 구현 +owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다. + +역할과 호출 조건은 [Agent 운영](SOLVER_AGENT_DESIGN.md), skill 적용은 +[Skill 설계](SOLVER_SKILL_DESIGN.md), 문서 원본과 소유권은 +[Feature 문서 관리](FEATURE_DOCUMENTATION.md), CLI·설정과 실패 진단은 +[Harness](HARNESS.md) 및 [동작 과정](HARNESS_WORKFLOW.md)을 따른다. + ## 후속 ADR 작성 기준 프로젝트 전체의 dependency 방향, 공통 identity·수명·결과 의미, 기술 baseline, diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4c04b21..df5824a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -37,13 +37,13 @@ Solver runtime └─ numerical backend 개발 운영 영역 -사용자 요구 → Coordinator → 담당 specialist → 산출물과 evidence → gate 판정 - │ - └─ 할당된 계획 / Harness / 코드·테스트·문서 변경 +사용자 요구 → 메인 assistant → 필요한 전문 작업·구현 → 검증·결과 확인 + │ + └─ 명시적 Harness / 코드·테스트·문서 변경 ``` 첫 흐름은 해석 데이터의 전달을, 두 번째는 개발 작업과 검증의 흐름을 나타낸다. -Agent, prompt, phase 파일과 Harness는 solver runtime API나 물리 모델의 일부가 아니다. +Agent, skill과 Harness는 solver runtime API나 물리 모델의 일부가 아니다. 개발 운영 영역은 저장소의 변경과 검증을 통제하며 solver가 실행 중 이를 호출하지 않는다. ## 공통 책임과 의존성 @@ -193,8 +193,10 @@ Diagnostic은 실패 단계, 안정된 code와 메시지, 가능한 source locat ## 검증과 reference 경계 검증 coverage와 비교량의 논리적 정의는 Numerical Review, 물리량의 저장·외부 대응은 -I/O, 실행 evidence는 Implementation, 독립 물리 판단은 Physics Evaluation이 소유한다. -각 단계는 상위 계약을 결과에 맞춰 수정하지 않는다. +I/O, 실행 evidence는 구현 담당자, 독립 물리 판단은 Physics Evaluation의 전문 책임이다. +메인은 작업에 필요한 전문 판단만 배정하며 고정 stage 순회를 요구하지 않는다. 수식·요소· +재료·적분·상태 갱신 변경에는 독립 수치 검토와 해당 analytical/invariant 검증을 수행한다. +각 담당자는 상위 계약을 결과에 맞춰 수정하지 않는다. - Source identity, location과 component 일치 여부를 수치 tolerance보다 먼저 확인한다. - Missing, extra, duplicate와 nonfinite required value를 숨기지 않는다. @@ -208,50 +210,40 @@ Architecture 문서의 그림이나 모듈명이 기능의 완료 증거를 대 ## 개발 운영 인프라 -공통 agent 상태 전이는 [SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill의 역할은 -[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실제 실행 절차는 -[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 agent/skill profile을 읽는다. +현행 운영은 [ADR-028](ADR.md#adr-028), 역할·인계는 +[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill 적용은 +[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실행 동작은 +[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 source·config에 대조한다. | Owner | 책임 | | --- | --- | -| Coordinator | Feature 문서 목록·상태, dispatch, evidence gate, revision·retry budget과 closure | -| Specialist | 할당된 stage의 전문 판단, 기본·상세 산출물과 공통 handoff | -| Planning Agent | 할당된 implementation plan과 phase/index/step 계획 파일 | -| Executor | 현재 step 선택, branch, transport attempt, timestamp, path-scoped commit과 phase 진행 | -| Implementation Agent | 선택된 step의 코드·테스트·보고서와 result payload | -| Hook | 도구 호출 전 guardrail과 설정된 종료 검증; TDD 관찰이나 완전한 sandbox의 대체가 아님 | +| 메인 assistant | 범위·작업 분해, 필요한 전문 작업 배정, 직접 계획·구현·수정, Feature context와 완료 evidence 확인 | +| Specialist | 할당된 전문 판단·파일과 간결한 결과; 상위 계약 문제를 owner와 메인에 전달 | +| 구현 담당자 | 메인 또는 implementation-agent로서 코드·테스트·관련 검증과 필요한 reference evidence 작성 | +| Harness runner | 명시 호출 시 config·project·toolchain 선택, adapter 계획 실행과 결과 반환 | +| Backend adapter/process | CMake/CTest 또는 MSBuild 명령 구성, argv/cwd·timeout·실패·결과 검사 | -Coordinator만 workflow를 전이한다. Specialist의 outcome은 전이 요청이고, Harness의 -step 상태는 별개의 실행 상태다. Executor transport attempt는 최대 2회이며 동일 -`retry_key`의 correction 1회와 뒤따르는 Implementation rerun은 Coordinator가 관리한다. -두 budget을 혼용하거나 실패 문구만 바꿔 반복하지 않는다. +Runner는 내부 LLM, phase 상태기계, 자동 Git·retry, 파일명 TDD gate나 대화 종료 hook을 +사용하지 않는다. 과거 phase/coordination 기록은 이력으로 보존한다. 일반 실패는 현재 +구현 owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다. -승인된 scope와 할당된 작업 안의 일반 계획·문서·local 실행에는 반복 승인 gate를 -추가하지 않는다. 계획 요청만으로 실행을 시작하지 않으며 외부 solver, 원격·파괴 작업과 -sandbox 권한 확대에는 해당 명시적 권한이 필요하다. +Project config·preset·command는 검토해야 할 실행 입력이다. Repository 경로 검사, +`shell=False`와 timeout이 실행 파일의 side effect를 모두 격리하는 sandbox는 아니다. +사용자 변경을 보존하고 실제 도구 권한과 외부 solver·원격·파괴 작업의 명시적 승인을 따른다. +승인된 일반 작업에 반복 승인을 추가하지 않으며 계획 요청만으로 실행을 시작하지 않는다. -Project config, preset과 실행 command는 검토해야 하는 실행 입력이다. Hook 통과나 -구조화된 argument list만으로 그 side effect가 격리되었다고 간주하지 않는다. -Executor는 시작 전 선택된 phase 제어 파일 밖의 변경을 거부하며 모든 pending Step의 -Planning 소유 `owned_paths`를 검증한다. 매 시도 후와 stage/commit 경계에서 신뢰된 목록과 -변경·staged 경로를 대조하고 구현 변경과 phase metadata를 분리한다. 범위 밖 변경은 -보존하고 재시도·커밋·다음 Step을 중단한다. 이 검사는 동시 writer의 원자적 격리나 여러 -커밋의 단일 transaction을 보장하지 않는다. 실행 중 동시 편집을 피한다. -종료 코드와 Step 보고 상태를 함께 판정하며 명시적 실패를 transport 재시도로 덮어쓰지 -않는다. 실제 wrapper timeout이고 결과 미보고일 때만 최초 포함 최대 두 번 시도한다. -환경·실패 진단과 원래 보고는 Executor 소유 `attempt_history`에 남기고 재개 때 보존한다. -등록된 Hook을 수동 실행하여 검증 evidence를 대신하지 않는다. - -문서 전용 Stop 생략은 기록된 동일 session/turn의 허용된 편집 대상이 모두 저장소 내부 -Markdown인 조건에 한정된다. 기록이 없거나 불완전한 읽기 전용 작업과 shell 쓰기까지 -안전하게 분류한다고 가정하지 않는다. 생략은 build/test 통과가 아니다. -사용자가 실행을 제외한 문서 작업은 정적 검토와 미실행 항목을 보고한다. +변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 계약상 필수 +reference 비교를 한 번 수행한다. 요청이나 넓은 영향으로 전체 검증이 필요한 경우에도 +실행하고 이후 변경·실패가 없으면 반복하지 않는다. 문서 작업은 정적 검토로 확인한다. +명령·exit code·판정값과 미실행 항목을 필요한 보고서에 기록하며 Harness 성공만으로 +물리·수치 correctness나 외부 release readiness를 선언하지 않는다. ## 문서와 아키텍처의 변경 프로젝트 공통 원칙의 변경은 공통 ADR로, 구현 항목별 선택은 해당 Feature ADR로 -기록한다. Feature PRD는 범위와 acceptance 요약을, requirements·formulation·I/O는 -전문 계약의 원본을 소유한다. 관리 문서와 기본·상세 산출물은 +기록한다. Feature PRD는 범위·작은 요구사항·acceptance와 현재 checklist의 원본이다. +복잡한 requirements·formulation·I/O는 필요한 경우에만 전문 문서로 분리하고 PRD에서 +참조하여 원본을 중복하지 않는다. 메인이 관리하는 핵심 문서 3개와 선택적 상세 산출물은 [FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)의 소유권과 링크 규칙을 따른다. Public dependency, identity, 수명, result meaning이나 lifecycle 변경은 영향받는 diff --git a/docs/CODINGSTYLE.md b/docs/CODINGSTYLE.md index e897acd..e3549fb 100644 --- a/docs/CODINGSTYLE.md +++ b/docs/CODINGSTYLE.md @@ -4,7 +4,7 @@ 이 문서는 FESA production 및 test C++의 코드 스타일, 객체 설계, 문서화와 검증 규칙을 정의하는 project-local source of truth다. 새 C++를 작성하거나 기존 C++를 리팩터링하는 -사람과 Implementation Agent는 작업 전에 이 문서를 읽어야 한다. +메인 assistant와 구현 담당자는 작업에 관련된 규칙을 확인한다. [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)를 baseline으로 사용한다. 이 문서, `AGENTS.md`, 승인된 feature contract와 architecture/ADR이 Google guide의 @@ -217,12 +217,14 @@ contract language는 현재 외부 계약을 유지한다. ## Test와 변경 관리 -- Production C++ 변경은 관련 C++ test와 같은 patch에 있어야 한다. -- Behavior 또는 interface 변경은 `RED -> observed failure -> minimal GREEN -> VERIFY`를 -따른다. +- Production 동작·interface 변경은 해당 의미를 확인하는 테스트를 추가·수정하여 검증한다. +- 버그는 가능한 경우 실패를 재현한 뒤 최소 수정하고 관련 검사를 실행한다. 기존 coverage가 + 충분한 rename/refactor에는 형식적인 새 테스트를 요구하지 않는다. - Refactoring test는 base interface 사용, ownership/lifetime, invalid combination, deterministic order와 current numerical result preservation을 검증한다. -- Focused test 뒤에 full MSVC x64 Debug build와 CTest를 실행한다. +- 개발 중에는 관련 검사를 실행하고, 솔버 기능 완료 시 full MSVC x64 Debug build와 CTest를 + 한 번 수행한다. 요청이나 넓은 변경 영향으로 필요한 경우에도 실행하며 이후 변경·실패가 + 없으면 반복하지 않는다. 문서만 수정할 때는 정적 검토를 수행한다. - B33/MITC4 output 경계를 건드린 변경은 승인된 reference comparison을 다시 실행한다. - Reference artifact, input path와 tolerance를 리팩터링에 맞춰 수정하지 않는다. - Commit은 review 가능한 module slice로 제한하고 Conventional Commits를 사용한다. @@ -243,14 +245,14 @@ doxygen Doxyfile Generated Doxygen HTML과 tool cache/build output은 source control에 넣지 않는다. -## Implementation Agent Checklist +## 구현 담당자 Checklist -Implementation Agent는 C++ Step을 시작하기 전에 다음을 확인한다. +메인 또는 구현 agent는 할당된 C++ 작업 전에 다음을 확인한다. -- 이 문서와 feature implementation plan을 읽었다. +- 관련 코딩 규칙·Feature 계약과 필요한 경우의 구현 계획을 확인했다. - 변경할 base/concrete/module owner가 승인 설계와 일치한다. -- 관련 test file과 RED condition이 Step에 명시되어 있다. +- 변경 동작을 확인할 검사와 가능한 버그 재현 조건을 정했다. - Public API naming과 production Doxygen가 이 문서에 맞는다. - Vendor dependency와 ownership direction이 역전되지 않는다. - Stable identity, numerical order, HDF5와 reference contract가 보존된다. -- Formatting, Doxygen, focused/full MSVC/CTest acceptance command가 계획되어 있다. +- Formatting, Doxygen와 변경 영향에 맞는 MSVC/CTest·reference 검증 범위 및 명령을 정했다. diff --git a/docs/FEATURE_DOCUMENTATION.md b/docs/FEATURE_DOCUMENTATION.md index 6877ba1..dc62d9c 100644 --- a/docs/FEATURE_DOCUMENTATION.md +++ b/docs/FEATURE_DOCUMENTATION.md @@ -1,79 +1,82 @@ # Feature 문서 관리 -이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면 -`docs//`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다. -``는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다. +지속할 요구사항·계약·검증 evidence가 필요한 solver Feature에는 `docs//`를 +사용한다. 메인 assistant가 안정적인 kebab-case Feature ID를 정하고 context와 문서 목록을 +관리한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다. +현재 운영은 [ADR-028](ADR.md#adr-028)과 [Agent 계약](SOLVER_AGENT_DESIGN.md)을 따른다. ## 시작과 참조 -1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를 - 재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다. -2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용 - 기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다. -3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고 - 자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는 - `AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다. -4. 기존 `docs/features//` 자료는 이력이므로 자동 이동하거나 복제하지 않는다. - 재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다. +1. 새 Feature 폴더를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다. + 재개 시 기존 계약과 evidence를 읽고 필요한 부분만 갱신한다. +2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 일반 Feature + 작업에서 읽기 전용 기준이다. Feature 진행 링크를 공통 문서에 누적하지 않으며 공통 + 지침 변경은 별도 사용자 요청 범위에서 수행한다. +3. Specialist는 할당 작업에 관련된 Feature 문서와 원문의 절만 읽는다. + `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니므로 필요한 context는 + 메인이 경로·절로 전달한다. 모든 인계에서 핵심 문서 3개를 재독하도록 강제하지 않는다. +4. 기존 `docs/features//`와 `coordination.md`는 이력으로 보존한다. + 자동 이동·복제하지 않고 재개에 필요한 경로·계약 revision을 참조한다. + `coordination.md`를 새로 생성하거나 현재 상태 기록을 위해 갱신하지 않는다. -이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의 -기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다. -Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당 -계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다. +Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 실제 상위 계약 문제는 +해당 owner와 메인에 evidence를 전달하고 필요한 사용자 결정을 따른다. -## Coordinator 관리 문서 +## 메인이 관리하는 핵심 문서 -| 문서 | 필요한 내용 | 참조 기준 | +| 문서 | 필요한 내용 | 프로젝트 기준 링크 | | --- | --- | --- | -| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` | -| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 | -| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 | -| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 | +| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당된 owner와 유용한 문서 목록. 현재 checklist는 PRD에 연결 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` | +| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본, 필요한 상세 계약 링크 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` | +| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거. 실제 결정이 없으면 그 사실과 적용 공통 결정 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` | -- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를 - 가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다. - 현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다. -- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에 - 결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로 - 표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다. -- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다. - Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다. -- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를 - 갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다. -- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자 - 요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다. +- 현재 checklist는 PRD 한 곳에서 관리한다. 문서 목록이나 별도 파일에 같은 상태를 + 중복 기록하지 않는다. +- 작은 요구사항·acceptance는 PRD에 직접 정의한다. 복잡하여 분리할 필요가 있을 때만 + `requirements.md`나 상세 verification matrix를 작성하고 PRD에는 요약과 링크를 둔다. + 분리된 전문 계약은 할당된 owner가 소유한다. +- 메인은 관련 반환을 확인하여 목록·링크·checklist를 갱신한다. Specialist는 할당된 + 문서만 수정하며 downstream이 upstream 계약을 결과에 맞춰 변경하지 않는다. +- 승인되지 않은 내용이나 아직 실행하지 않은 검증을 승인·완료로 표시하지 않는다. + 일반 문서 작성·업데이트를 위해 반복적인 승인 gate를 추가하지 않는다. +- 각 핵심 문서는 실제 프로젝트 기준을 상대 Markdown 링크로 연결한다. 필요한 운영 + 설명은 `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md`를 참조한다. -## Agent 산출물 작성 +## 필요한 상세 문서와 evidence -각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되 -필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다. +결과를 지지하는 다음 내용만 필요한 만큼 기록한다. -1. 식별: Feature ID, owner, 입력 contract revision. -2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견. -3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값. -4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조. +1. 해당 Feature·작업·owner와 적용 계약 또는 관련 revision. +2. 판단·결정, 구현·검토에 필요한 정의와 주요 발견. +3. 출처·evidence 경로, 실제 명령·exit code·결정적 측정값과 적용 기준. +4. 가정, 미지원 범위, 미해결 항목·제한과 다음 작업에 필요한 정보. -상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement, -수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다. -분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다. +`research.md`, `formulation.md`, `io.md`, `numerical-review.md`, +`reference-model.md`, `implementation-report.md`, `build-test.md`, +`reference-comparison.md`, `physics-evaluation.md`는 필요한 경우의 산출물 예시다. +간단한 구현·build/test·reference 결과는 하나의 짧은 보고서에 모을 수 있으며 같은 결과를 +여러 기본 보고서에 반복하지 않는다. Release 보고서는 명시적으로 감사를 요청한 경우에만 작성한다. -긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에 -`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를, -`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다. +긴 유도·전체 schema·mapping·검증 matrix가 필요하면 같은 폴더의 +`formulation-derivation.md`, `io-schema.md` 같은 문서로 분리하여 관련 본문에서 연결한다. +상세 문서는 해당 전문 owner가 소유하고 적용되는 계약과 기본 문서를 명확히 연결한다. +반환할 때 판단에 사용한 상세 evidence 경로도 포함한다. 고정 envelope나 모든 산출물의 +hash·gate 기록은 요구하지 않는다. -- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만 - 적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다. -- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도 - 기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다. -- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세 - 문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다. -- 모든 agent 보고서는 `docs//`에 저장한다. 소스·테스트·Harness 제어 파일과 - 기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서 - 참조한다. +짧게 쓰기 위해 필수 수식·identity·units·schema·tolerance·acceptance 정의를 없애지 않는다. +문서만 수정할 때 원시 로그나 의미 변화 없는 revision 기록을 추가하지 않는다. 실제 계약이 +변경되면 관련 evidence가 여전히 유효한지 확인하며 과거 결과를 현재 검증으로 소급하지 않는다. +필수 검증을 실행하지 않았다면 미실행 사실과 이유를 남긴다. -## Gate 확인 +소스·테스트·기계 생성 로그/결과·read-only reference artifact는 각자의 지정 경로에 유지하고 +보고서에서 참조한다. 기존 phase 이력은 새 보고서 형식에 맞추어 변경하지 않는다. +Reference artifact와 tolerance를 구현 결과에 맞추어 수정하지 않는다. -Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다. -판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다. -필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의 -검증을 대신하지 않는다. +## 언어와 확인 + +기본 Feature 문서는 한국어 Markdown으로 작성하고 agent/skill ID, field, requirement ID, +경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ--###`다. + +메인은 실제 파일·소유권·상대 링크와 판단에 필요한 evidence를 확인한다. 필수 상세 근거가 +없거나 연결이 끊겼다면 해당 owner와 해결하고 요약만으로 검증을 대신하지 않는다. +문서 정리는 정적 검토로 확인하며 solver build나 수치/reference 검증의 통과로 보고하지 않는다. diff --git a/docs/HARNESS.md b/docs/HARNESS.md index f6c90e3..f9cbec9 100644 --- a/docs/HARNESS.md +++ b/docs/HARNESS.md @@ -1,84 +1,46 @@ # Harness 운영 가이드 -## Requirements +## 목적과 준비 환경 -Windows와 Codex CLI가 필요하다. Executor는 Python 3.10 이상을 사용하며, 이 저장소의 -계약 테스트는 표준 `tomllib`을 사용하므로 검증 환경은 Python 3.11 이상으로 준비한다. +Harness는 명시적으로 호출하는 repository build/test 실행기다. +[Agent 운영](SOLVER_AGENT_DESIGN.md)과 [Harness skill](../.agents/skills/harness/SKILL.md)에 +따라 필요한 검증을 수행하며 내부 Codex 호출, phase 관리, 자동 Git 처리와 대화 종료 +hook을 사용하지 않는다. 현재 운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다. + +Runner에는 Windows와 Python 3.10 이상이 필요하다. 저장소의 `tomllib` 기반 Python 검사는 +Python 3.11 이상을 사용한다. Runner 자체는 Codex CLI를 필요로 하지 않는다. FESA는 Visual Studio의 Desktop development with C++ 워크로드, CMake/CTest와 Ninja를 -사용한다. MSVC x64 developer 환경과 dependency 경로는 [AGENTS.md](../AGENTS.md)의 -최소 검증 진입점을 따른다. +사용한다. MSVC x64 developer 환경에서 `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, +`HDF5_DIR`를 설치된 dependency 경로로 설정한다. 상세 기준은 +[프로젝트 지침](../AGENTS.md)의 최소 검증 진입점을 따른다. -역할·승인·상태 전이는 [Agent 계약](SOLVER_AGENT_DESIGN.md)과 -[Harness skill](../.agents/skills/harness/SKILL.md)을 따른다. 이 문서는 설치·실행 참고이며 -solver Feature의 9개 stage와 evidence gate를 대신하지 않는다. +## 명시적 실행과 설정 선택 -## 프로젝트 자동 감지 - -프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의 -CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는 -건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는 -오류로 처리한다. - -설정 파일은 선택 사항이다. 기본 자동 감지와 `.harness/build` 경로를 그대로 사용할 -때는 만들지 않아도 된다. 프로젝트별 override가 필요하면 다음처럼 예시를 복사한다. +저장소 루트에서 구성된 전체 검증을 한 번 실행한다. ```powershell -Copy-Item .harness/config.example.json .harness/config.json +python scripts/execute.py ``` -승인된 Feature와 Coordinator dispatch에 따라 Planning Agent가 할당된 phase 파일을 -작성한다. 일반 계획 파일 작성에 반복 승인을 요구하지 않는다. 실행까지 할당된 경우에만 -다음 명령을 사용하며, 계획 작성 요청만으로 Executor를 시작하지 않는다. +개발 중 focused check는 선택된 backend의 실제 명령을 직접 실행한다. 솔버 기능 완료 시 +구성된 전체 build/test와 계약상 필수 reference 비교를 수행하고 이후 변경·실패가 없으면 +반복하지 않는다. 문서만 변경하는 작업에서는 정적 검토를 하고 build/test를 실행하지 않는다. -```powershell -python scripts/execute.py -``` +Runner는 자신의 script 위치를 기준으로 저장소 root를 정하고 `.harness/config.json`을 +읽는다. 설정이 없으면 기본 자동 감지를 사용한다. 선택 순서는 명시한 `projectType`, +설정된 CMake source directory의 metadata, root의 단일 `.sln`, 단일 `.vcxproj`다. +여러 solution/project로 선택이 모호하면 명시 설정이 필요하다. C++ source 전체를 +scan하거나 metadata 없는 C++ 파일의 존재로 별도 gate를 적용하지 않는다. -`--push`는 해당 원격 push를 사용자가 명시적으로 승인했을 때만 추가한다. 실행 전 -Git top-level은 Harness root와 같고 선택된 phase 제어 파일 밖의 worktree는 clean이어야 -한다. 실행 중 동시 편집과 커밋 범위의 한계는 [동작 과정](HARNESS_WORKFLOW.md)을 따른다. +현재 [config 예시](../.harness/config.example.json)는 `projectType=cmake`와 +`cmake.sourceDir=.`만 지정한다. 개인 설정이 필요할 때 참고하되 기존 설정을 무조건 +덮어쓰지 않는다. Preset 없는 기본 binary directory는 `.harness/build`다. -모든 `pending` Step에는 승인된 정확한 상대 파일 목록인 `owned_paths`가 필요하다. -누락된 기존 phase는 Planning의 할당된 준비 작업에서 목록을 보완한 뒤 실행한다. -`[]`는 구현 파일 변경이 없음을 뜻하며 완료 이력에는 목록을 소급 추가하지 않는다. -Executor는 실행 후와 staging/commit 경계에서 소유권을 검사하며 범위 밖 변경은 -보존하고 중단한다. 상세 schema와 제한은 [Harness skill](../.agents/skills/harness/SKILL.md)을 따른다. +## FESA CMake preset 설정 -Executor가 시작하는 Codex 세션은 기본적으로 `workspace-write` sandbox를 사용한다. -Windows native sandbox에서 MSVC compiler-id의 `cl.exe`가 정지하는 것이 재현되고 같은 -명령이 sandbox 밖에서 정상 완료되는 경우에만, 사용자 승인을 받은 격리된 clean -linked Git worktree에서 다음처럼 해당 실행에 한정해 fallback을 지정할 수 있다. - -```powershell -$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access" -python scripts/execute.py --approve-danger-full-access -Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX -``` - -허용값은 `workspace-write`와 `danger-full-access`뿐이다. 후자는 Codex Step에 workspace -밖의 파일 접근 권한도 부여하므로 일반 기본값으로 설정하지 않는다. 어느 모드에서도 -`.codex/hooks.json`의 등록된 hook을 비활성화하지 않는다. 환경변수만으로 권한이 승인되지 -않으며 Executor는 승인 flag가 없거나 primary/dirty worktree인 권한 상승 실행을 거부한다. - -Stop은 유효한 동일 session/turn 편집 기록의 대상이 모두 저장소 내부 `.md`일 때만 -build/test를 생략한다. 기록 누락·손상 또는 비문서 편집은 정상 검증 경로를 따른다. -Shell 쓰기나 편집 기록 없는 읽기 전용 요청도 자동 생략을 보장하지 않는다. 문서 작업에서 -사용자가 실행을 제외하면 수동으로 Hook·build/test를 실행하지 않고 미검증 사실을 보고한다. - -## Harness Python 검증 - -이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고 -다음 명령으로 실행한다. - -```powershell -uv run --with pytest python -B -m pytest -v -rs -``` - -## CMake preset 설정 - -`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`, -`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께 -지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다. +FESA의 현재 [CMakePresets.json](../CMakePresets.json)을 사용하려면 다음 필드를 +`.harness/config.json`에 함께 지정한다. Preset 파일의 존재나 config 예시 복사만으로 +Runner가 preset 이름을 선택하지는 않는다. ```json { @@ -94,6 +56,9 @@ uv run --with pytest python -B -m pytest -v -rs } ``` +`configurePreset`, `buildPreset`, `testPreset`, `binaryDir`는 함께 지정해야 한다. +이에 대응하는 backend 명령은 다음과 같다. + ```powershell cmake --preset windows-msvc-ninja-debug cmake --build --preset windows-msvc-ninja-debug @@ -101,10 +66,8 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1 ctest --preset windows-msvc-ninja-debug --output-on-failure ``` -위 예시는 현재 [CMakePresets.json](../CMakePresets.json)과 -[config 예시](../.harness/config.example.json)에 맞춘다. Preset 파일이 존재하는 것만으로 -Stop이 그 preset을 선택하지는 않는다. 아래는 preset을 쓰지 않는 adapter의 명령 형태이며, -FESA에서는 dependency 경로와 승인된 build 구성을 함께 확인한다. +아래는 preset 없는 CMake adapter의 기본 명령 형태다. FESA에서는 승인된 MSVC x64 Debug +구성과 dependency 경로를 함께 확인한다. ```powershell cmake -S . -B .harness/build -A x64 @@ -113,14 +76,14 @@ ctest --test-dir .harness/build -C Debug --show-only=json-v1 ctest --test-dir .harness/build -C Debug --output-on-failure ``` +Runner는 configure 후 MSVC compiler metadata를 확인하고 CTest discovery가 0개이면 +실패로 처리한다. Build/test 성공이 물리·수치 correctness나 별도 필수 reference 비교의 +통과를 대신하지 않는다. Runner는 Feature 문서에서 추가 비교 명령을 추론하지 않는다. + ## 직접 MSBuild 설정 -다음은 재사용 가능한 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며 -이 예시로 solution-only MSBuild 검증을 대체 승인하지 않는다. - -`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을 -지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행 -파일과 인수를 JSON 배열로 적는다. +다음은 재사용 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며 +solution-only MSBuild를 승인된 대체 검증으로 간주하지 않는다. ```json { @@ -135,46 +98,57 @@ ctest --test-dir .harness/build -C Debug --output-on-failure } ``` +`msbuild.testCommand`는 필수 argv 배열이며 실행 파일은 repository-relative 경로로 +지정한다. 선택한 solution/project를 build한 뒤 testCommand를 한 번 실행한다. + +## 결과와 실패 진단 + +| 상황 | Runner 결과 | +| --- | --- | +| 구성된 build/test와 결과 검사가 모두 성공 | exit 0, 명령·cwd·exit code와 test 출력 요약 | +| 잘못된 config, 모호한 감지, toolchain/adapter 오류, backend 실패·timeout | exit 1 | +| 명시한 projectType의 metadata가 없음 | exit 1 | +| Non-MSVC compiler 또는 CTest 0개/잘못된 discovery 결과 | exit 1 | +| 자동 감지에서 CMake/MSBuild metadata가 없음 | `not configured`, exit 2 | +| 지원하지 않는 CLI 인자 | usage error, exit 2; 검증 미시작 | + +Backend nonzero는 실패 진단에 원래 값으로 남지만 runner의 반환값은 1이다. +대상 부재나 미실행을 검증 통과로 표시하지 않는다. 실패 시 stage, argv, cwd와 가능한 +출력 tail을 확인한다. 실패 후 자동 재시도나 후속 단계를 실행하지 않는다. + +- Visual Studio 도구가 없으면 C++ workload와 설치 경로를 확인한다. +- Solution/project 선택이 모호하면 `projectType`, `msbuild.solution`을 명시한다. +- Compiler가 MSVC가 아니면 선택된 환경과 toolchain 설정을 확인한다. +- CTest가 0개이면 `enable_testing()`과 테스트 등록을 확인한다. +- MSBuild test command가 없으면 실제 테스트 실행 파일과 인수를 설정한다. +- Timeout·실패 원인은 현재 구현 owner가 수정한다. 새 근거나 변경 없이 반복 실행하지 않는다. + +Runner 전체 deadline은 config·discovery·toolchain 탐색을 포함해 1,800초다. 각 명령에는 +남은 전체 시간과 명령별 timeout 중 짧은 값을 적용한다. 실행·검사 경계는 +[동작 과정](HARNESS_WORKFLOW.md)을 따른다. + +## 이전 운영 방식에서 달라진 점 + +옛 `python scripts/execute.py ` 호출과 `--push`, +`--approve-danger-full-access` 인자는 usage error로 거부한다. Phase import나 상태 +migration은 제공하지 않으며 기존 `phases/` 기록을 읽거나 수정하지 않는다. + +Legacy `tdd` config는 설정 로드 때 폐기 안내를 한 번 출력하고 무시한다. +`testRoots`·`testPatterns`·`exclude`에 의한 대응 파일명 gate는 없다. 개인 config는 +자동 수정하지 않으므로 사용자가 필요할 때 해당 항목을 제거할 수 있다. + +전용 phase executor, 자동 branch/commit/push·retry, PreToolUse/Stop과 자체 sandbox 승인 +환경변수는 사용하지 않는다. Git 상태를 변경하거나 commit할 권한은 runner 실행에서 +생기지 않는다. Config·preset·명령은 검토할 실행 입력이며 `shell=False`와 경로 검사는 +완전한 sandbox가 아니다. 실제 도구 권한과 외부 실행의 명시적 승인 경계는 유지한다. + +## Harness Python 검증 + +Harness 구현을 변경하여 Python 검증이 필요할 때 다음 명령을 사용한다. 개발 중에는 +관련 검사만 선택하고 전체 검사가 필요한 최종 변경 후 한 번 실행한다. + ```powershell -MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64 -.\build\tests\Debug\MyProjectTests.exe +uv run --with pytest python -B -m pytest -v -rs ``` -## TDD 확장 - -`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다 -`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은 -기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를 -대체하지 않고 추가한다. - -```json -{ - "version": 1, - "tdd": { - "testRoots": ["tests", "integration-tests"], - "testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"], - "exclude": ["legacy/generated/**"] - } -} -``` - -## 실패 복구 - -Executor는 명시적 `error/blocked`를 비정상 종료에서도 보존하며 자동 재시도하지 않는다. -인식된 sandbox helper 환경 오류는 종료 코드 0에서도 Step과 상위 phase를 `blocked`로 -기록한다. 실제 wrapper timeout으로 결과를 받지 못했을 때만 최초 포함 최대 두 번 시도한다. -원인 미분류 nonzero와 `completed`/nonzero 불일치는 `error`다. 환경 차단은 종료 코드 2, -일반 실패는 1이며 preflight 실패는 branch/state 변경 전에 반환한다. - -- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다. -- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다. -- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다. -- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다. -- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다. -- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리, - 종료 코드와 출력 tail을 확인한다. 실행이 할당된 범위에서만 재현 명령을 수행하며 - 문서 작업의 검증 제외 지시를 덮어쓰지 않는다. Stop은 별도의 빌드 로그 파일을 만들지 않는다. -- 실패 분류와 재시작 결정은 Coordinator가 기록한다. Planning Agent는 명시적으로 할당된 - 복구 작업에서만 현재 실패 Step의 status를 `pending`으로 바꾸고, Executor가 재시작 시 - 오래된 outcome 필드와 timestamp를 정리하되 `attempt_history`는 보존한다. 실패 evidence를 먼저 보존하며 - 상세 절차는 [Harness skill](../.agents/skills/harness/SKILL.md)의 Recovery and handoff를 따른다. +실제 검사 결과와 미실행 항목을 구분해 보고한다. 문서만 갱신할 때는 이 명령을 실행하지 않는다. diff --git a/docs/HARNESS_WORKFLOW.md b/docs/HARNESS_WORKFLOW.md index 1569ba4..02de807 100644 --- a/docs/HARNESS_WORKFLOW.md +++ b/docs/HARNESS_WORKFLOW.md @@ -1,693 +1,109 @@ -# Harness Framework 동작 과정 +# Harness 동작 과정 -이 문서는 자연어 요구사항을 받은 뒤 Harness Framework가 계획을 만들고, 독립된 -Codex 세션에서 Step을 실행하고, MSVC로 C++ 프로젝트를 검증하는 전체 과정을 -설명한다. 설치 및 설정 예시는 [Harness 운영 가이드](HARNESS.md)를 참고한다. +## 개발 작업과 명시적 검증 -Feature의 9개 정규 stage와 Coordinator의 gate 전이는 -[Agent 계약](SOLVER_AGENT_DESIGN.md), 역할별 절차는 -[Harness skill](../.agents/skills/harness/SKILL.md), 문서 소유권은 -[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다. Harness는 그중 할당된 -구현 계획·Step 실행을 지원하며, solver workflow 전체를 대신하지 않는다. - -## 1. 핵심 구조 - -Harness Framework는 다음 세 계층으로 구성된다. - -1. **계획 계층**: 승인된 요구사항과 Coordinator dispatch를 실행 가능한 Step으로 변환한다. -2. **실행 계층**: Step Executor가 Step마다 독립 Codex 세션을 실행하고 상태와 Git - 커밋을 관리한다. -3. **검증 계층**: PreToolUse 훅이 편집 전 정책을 검사하고, Stop 훅이 종료 전 MSVC - 빌드와 테스트를 실행한다. 유효한 문서 전용 편집 기록이면 조건부로 생략한다. - -전체 흐름은 다음과 같다. +메인 assistant가 관련 계약과 변경 범위를 확인하고 필요한 전문 작업만 위임한다. +현재 역할과 사용자 결정 경계는 [Agent 운영](SOLVER_AGENT_DESIGN.md), +문서 관리는 [Feature 문서 관리](FEATURE_DOCUMENTATION.md), +운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다. ```text -사용자 요구사항 - ↓ -Feature의 선행 계약·gate 확인 - ↓ -Coordinator의 bounded Planning dispatch - ↓ -Planning Agent의 자기완결적 Step 작성 - ↓ -phases/index.json, task index, stepN.md 생성 - ↓ -실행까지 할당된 경우 Step Executor 시작 - ↓ -각 Step을 독립 Codex 세션에서 실행 - ├─ 도구 호출 전: PreToolUse 정책 검사 - └─ 응답 종료 전: Stop 검증 또는 문서 전용 조건부 생략 - ↓ -성공: 커밋 후 다음 Step -transport 실패: 최초 포함 최대 2회 시도 -구현 실패·차단: Coordinator로 반환 +관련 계약·현재 evidence 확인 → 변경 → 관련 test/build → 결과 확인 + │ + └─ 기능 완료 시 전체 build/test·필수 reference 비교 ``` -자연어 요구사항이나 계획 요청만으로 Executor가 자동 시작되지는 않는다. 승인된 Feature와 -dispatch 안의 일반 계획 파일 작성·할당된 실행에 반복 승인 gate를 추가하지 않는다. -권한 상승, 원격·파괴 작업, licensed reference solver 실행은 별도 명시적 승인이 필요하다. +동작 변경에는 해당 의미를 확인하는 테스트를 추가·수정한다. 버그는 가능한 경우 실패를 +재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적인 +새 테스트를 요구하지 않는다. 계획·소스·테스트·evidence는 할당된 범위 안에서 변경한다. -## 2. 요구사항 탐색과 구체화 +개발 중 focused check는 실제 configured backend 명령으로 수행한다. +`python scripts/execute.py`는 구성된 전체 build/test를 한 번 실행한다. 사용자가 요청하거나 +넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되, 이후 변경·실패가 없으면 반복하지 +않는다. 계획 작성만 요청받은 경우에는 실행하지 않는다. -예를 들어 사용자가 다음 요구사항을 전달했다고 가정한다. +## 변경 종류별 검증 -아래 Calculator 예시는 Harness Step 구조를 설명하기 위한 것으로 FESA 제품 요구사항이나 -새 기능 구현 지시가 아니다. +| 작업 | 수행할 작업과 확인 | +| --- | --- | +| 문서 수정 | 관련 문서·소스·링크·diff 정적 확인. Solver build, 새 테스트, 별도 specialist 호출을 의무화하지 않음 | +| 일반 구현 버그 | 메인 또는 기존 구현 owner가 가능한 실패 재현 → 최소 수정 → 관련 검사. 변경 영향·기능 완료 조건에 따라 전체 검증 | +| 새 수치 기능 | 필요한 요구·정식화·I/O 정의, 독립 numerical review → 구현·관련 테스트 → 전체 build/test와 필수 analytical/invariant·물리·reference 검증 | -> CMake 기반 C++20 라이브러리에 `divide()` 함수를 추가하고, 0으로 나누면 예외를 -> 발생시키며 GoogleTest 테스트를 작성한다. +수식·요소·재료·적분·상태 갱신 변경에는 독립 numerical review를 수행한다. 물리/수치 +검증은 각 계약에 따라 수행하며 역할이나 보고서 수를 줄였다는 이유로 생략하지 않는다. +Release-readiness 감사는 명시적으로 요청할 때만 수행한다. -계획을 작성하기 전에 다음 자료를 확인한다. +## Runner의 실행 순서 -- `AGENTS.md` -- `docs/PRD.md` -- `docs/ARCHITECTURE.md` -- `docs/ADR.md` -- Coordinator dispatch와 `docs//`의 승인된 선행 계약 -- 해당 Feature의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md` -- 관련 제품 코드와 테스트 -- `.harness/config.json`이 있으면 그 설정, 없으면 preset·metadata·프로젝트 지침과 감지 기본값 +[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를 반환한다. -- 사용하는 MSVC toolset과 C++ 표준 -- CMake 프로젝트인지 Visual Studio solution/project인지 -- 테스트 프레임워크와 테스트 실행 방법 -- public header와 implementation의 의존성 방향 -- 수정할 모듈과 범위 밖 항목 -- 실행 가능한 Acceptance Criteria 명령 +여기서 검증 계획은 backend 명령 목록이다. Feature phase/index/step 파일이나 LLM +프롬프트가 아니다. Runner는 Git branch·HEAD·index를 관리하거나 Feature 문서를 +해석해 추가 명령을 생성하지 않는다. -필수 계약이 없으면 Coordinator를 통해 해당 owner로 반환한다. 예외 타입, 수치 타입, -public API·ABI처럼 승인된 의미를 바꾸는 선택은 critical decision 기준에 따라 사용자에게 -올린다. 이미 승인된 계약 안의 파일 배치나 테스트 분해는 담당자가 결정한다. +### Backend별 실행 -## 3. 요구사항을 Step으로 분해 +| Backend | 실행과 결과 검사 | +| --- | --- | +| CMake/CTest | configure → compiler metadata의 MSVC 확인 → build → CTest JSON discovery/0개 거부 → test | +| MSBuild | 선택된 solution/project build → 명시된 repository-relative testCommand 실행 | -사용자가 구현 계획 작성을 요청하면 요구사항을 작은 Step으로 나눈다. Step 설계 -규칙은 [Harness Workflow](../.agents/skills/harness/SKILL.md)에 정의되어 있다. +FESA는 CMake/MSVC x64/Debug와 CTest를 제품 검증 기준으로 사용한다. +MSBuild adapter가 있다는 사실이 solution-only 검증을 대체 승인하지 않는다. +Preset 선택과 정확한 명령·설정 예시는 [Harness 운영 가이드](HARNESS.md)를 따른다. -각 Step은 다음 조건을 만족해야 한다. +## 실행 경계와 실패 처리 -- 하나의 모듈 또는 명확한 한 가지 책임만 다룬다. -- 다른 대화 내용을 참조하지 않아도 실행할 수 있도록 자기완결적으로 작성한다. -- 먼저 읽을 문서와 이전 Step의 관련 파일을 명시한다. -- Feature 관리 문서와 승인된 선행 계약의 정확한 경로·revision을 명시한다. -- 클래스와 함수 시그니처 수준으로 작업 범위를 설명한다. -- 수정할 소스·테스트·보고서 파일과 수정하지 않을 upstream 파일을 명시한다. -- 실제 실행 가능한 빌드·테스트 명령을 Acceptance Criteria로 사용한다. -- 성공, 오류, 사용자 개입 필요 상태의 판정 기준을 적는다. -- 범위 밖 기능과 기존 테스트 회귀를 명시적으로 금지한다. +Config의 경로와 명령 cwd는 repository 범위 안인지 확인한다. MSBuild testCommand의 +실행 파일도 repository-relative 경로여야 한다. Subprocess는 argv 배열과 `shell=False`로 +실행하며 stdout/stderr를 수집한다. Config·preset·실행 파일 자체의 side effect까지 격리하는 +sandbox는 아니므로 실제 실행 입력과 도구 권한을 확인한다. -예시 Step은 다음과 같은 내용을 포함할 수 있다. +전체 deadline은 시작부터 1,800초다. 각 명령의 timeout은 남은 전체 시간과 명령별 제한 중 +짧은 값이며, 실행 전 남은 시간이 없으면 실패한다. Backend nonzero, timeout, MSVC 확인 +실패나 CTest 0개 등 결과 검사 실패가 발생하면 후속 단계를 실행하지 않는다. -```text -Step 0: division-api +명령 실패 진단에는 stage·argv·cwd, 가능한 원래 exit code와 출력 tail이 포함된다. +현재 구현 owner가 원인을 확인하고 필요한 수정 또는 환경 조치 후 관련 검사를 수행한다. +새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않으며 자동 transport retry나 +별도 correction 예산은 없다. -읽어야 할 파일 -- AGENTS.md -- include/calculator.hpp -- src/calculator.cpp -- tests/calculator_test.cpp +Runner는 성공 시 exit 0, config/toolchain/backend 등 실행 실패 시 exit 1을 반환한다. +자동 감지에서 metadata가 없거나 CLI 인자가 잘못되면 exit 2다. 명시된 projectType에 필요한 +metadata가 없는 경우는 exit 1이다. Backend 원래 nonzero와 runner exit를 구분한다. +전체 목록은 [결과와 실패 진단](HARNESS.md#결과와-실패-진단)을 참조한다. -작업 -- divide(double lhs, double rhs)의 실패 테스트를 먼저 추가한다. -- rhs가 0이면 std::invalid_argument가 발생하도록 최소 구현한다. +## 수치 evidence와 완료 확인 -Acceptance Criteria -- CMake/MSBuild 빌드가 성공한다. -- 전체 테스트가 성공한다. -- 새로운 컴파일러 경고가 없다. -``` +Harness 성공은 build/test 실행 결과다. 필요한 reference comparison을 자동 탐색하거나 +솔버 correctness 전체를 판정하지 않는다. 메인·구현 담당자는 계약이 요구하는 다음 +검증을 별도로 확인한다. -### TDD와 Step 경계 +- 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·실패 보존·결정론과 필요한 독립 물리 판단 -프로젝트 규칙은 실패하는 테스트를 먼저 요구하지만 Stop 훅은 Codex가 Step을 종료할 -때 전체 테스트 성공을 요구한다. 따라서 다음처럼 실패 상태를 Step 사이에 남겨둘 수 -없다. +Reference artifact와 tolerance를 통과에 맞춰 수정하지 않는다. 명령·exit code와 결정적 +판정값은 필요한 보고서에 한 번 기록하고 원시 로그는 원본 경로로 연결한다. 실패·미실행· +stale evidence와 미해결 항목을 명확히 남기며 검사를 생략한 사실을 통과로 보고하지 않는다. -```text -Step 0: 실패하는 테스트만 추가하고 종료 -Step 1: 제품 코드를 구현해 테스트 통과 -``` +## 과거 phase·hook·Git 처리 -실제 red-green 순서는 하나의 Codex 실행 안에서 완료되어야 한다. +현재 runner는 내부 Codex 세션, phase 상태기계·result payload, `owned_paths`· +`attempt_history`, 자동 branch/commit/push, PreToolUse/Stop을 사용하지 않는다. +`coordination.md`와 기존 phase·hook 기록은 이력으로 보존하고 새 실행 입력으로 만들지 않는다. -```text -테스트 작성 -→ 테스트 실패 확인 -→ 최소 제품 코드 구현 -→ 테스트 성공 확인 -→ Step 종료 -``` - -즉, 테스트가 구현보다 먼저 작성되는 순서는 지키되 각 Step은 최종적으로 green -상태여야 한다. - -## 4. 할당된 계획 산출물 - -Planning Agent는 Coordinator가 할당한 다음 파일을 생성한다. 기존 산출물을 재개할 때는 -덮어쓰지 않고 승인된 변경 범위만 갱신한다. Step 번호는 0부터 연속으로 둔다. - -```text -phases/ -├── index.json -└── add-division/ - ├── index.json - ├── step0.md - ├── step1.md - └── ... -``` - -### 4.1 Top-level index - -`phases/index.json`은 여러 task의 상태를 관리한다. - -```json -{ - "phases": [ - { - "dir": "add-division", - "status": "pending" - } - ] -} -``` - -### 4.2 Task index - -`phases/add-division/index.json`은 task 내부 Step의 상태를 관리한다. - -```json -{ - "project": "Calculator", - "phase": "add-division", - "steps": [ - { - "step": 0, - "name": "division-api", - "status": "pending", - "owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"] - } - ] -} -``` - -상태별 기록은 다음과 같이 나뉜다. - -`owned_paths`는 Planning이 작성하는 정확한 저장소 상대 파일 목록이다. Step 본문의 소유 -파일과 일치해야 하며 source/header/test/build/report를 필요한 만큼 명시한다. 디렉터리, -glob, 절대 경로, 경로 이탈, Git 내부와 `phases/` 제어 경로는 허용하지 않는다. 연결된 -파일·디렉터리 경로도 지원하지 않는다. `[]`는 구현 파일 변경 없음이며 누락과 다르다. -기존 완료 Step은 필드 없이 읽을 수 있지만 모든 pending Step은 실행 전에 목록이 필요하다. -기존 phase를 일괄 변환하거나 Markdown에서 파일 권한을 자동 추출하지 않는다. - -| 상태 | Codex가 기록 | Executor가 기록 | -|---|---|---| -| `completed` | `summary` | `completed_at` | -| `error` | `error_message` | `failed_at` | -| `blocked` | `blocked_reason` | `blocked_at` | - -Executor는 task의 `created_at`과 Step의 `started_at`, `attempt_history`도 기록한다. -History에는 단조 증가하는 `attempt`, `recorded_at`, `exit_code`(프로세스 미기동은 null), -`reported_status`, `reported_reason`, 로컬 `classification`·판정 `reason`과 `diagnostic`을 보존한다. -진단은 stderr 우선, 없으면 stdout의 마지막 4,000자이며 raw output 전체의 대체가 아니다. -Implementation은 `owned_paths`·history·timestamp를 수정할 수 없다. `summary`는 다음 -독립 Codex 세션이 이전 Step의 핵심 산출물과 결정을 이해할 수 있도록 한 줄로 -작성한다. - -### 4.3 Step 파일 - -각 `stepN.md`에는 다음 내용이 들어간다. - -- 읽어야 할 파일 -- 작업 범위와 인터페이스 -- 핵심 동작 및 불변 조건 -- Acceptance Criteria 명령 -- 아키텍처·ADR·CRITICAL 규칙 확인 절차 -- 성공, 오류, 차단 상태 기록 방법 -- 범위 밖 변경 금지사항 - -Step은 독립 Codex 실행의 전체 작업 지시서이므로 이전 대화만 참조하는 표현을 넣지 -않는다. - -## 5. Step Executor 시작 - -계획 파일이 준비되고 실행까지 할당된 경우 다음 명령으로 실행한다. - -```powershell -python scripts/execute.py add-division -``` - -완료된 브랜치의 원격 push를 사용자가 명시적으로 승인한 경우에만 `--push`를 추가한다. - -```powershell -python scripts/execute.py add-division --push -``` - -[Step Executor](../scripts/execute.py)는 시작할 때 다음 작업을 수행한다. - -1. phase 경로와 top-level/phase index schema, Step 번호·이름·상태를 검사한다. -2. 현재 첫 미완료 Step이 `error` 또는 `blocked`이면 복구 결정 전까지 중단한다. -3. 모든 pending Step의 `owned_paths`, Implementation Agent profile, Git top-level, - sandbox 승인 조건과 clean 상태를 검사한다. - 기본 모드는 선택된 phase 제어 파일 allowlist 밖의 변경을 허용하지 않는다. -4. `feat-{phase-name}` 브랜치를 생성하거나 checkout한다. -5. `AGENTS.md`와 `docs/*.md`를 guardrail로 읽는다. -6. task/Step timestamp와 재개 상태를 정리하고 첫 번째 `pending` Step부터 순차 실행한다. - -`AGENTS.md`와 모든 `docs/*.md` 내용은 각 Codex 프롬프트에 직접 삽입된다. 따라서 -이 문서들도 실행 입력에 포함된다. 역할·승인·상태 전이에서는 Agent 계약과 Harness skill의 -권한 경계를 따르며, 설치 예시를 Feature의 요구사항으로 사용하지 않는다. Feature 관리 -문서는 자동으로 로드되지 않으므로 dispatch와 Step의 필수 입력 경로에 명시해야 한다. - -## 6. Step마다 독립 Codex 세션 실행 - -Executor는 각 Step을 다음 형태의 독립 프로세스로 실행한다. - -```text -codex exec - --disable unified_exec - --json - --model - --config model_reasoning_effort="" - --sandbox - --dangerously-bypass-hook-trust - --cd - - -``` - -기본값은 `workspace-write`다. `FEM_HARNESS_CODEX_SANDBOX` 환경 변수는 -`workspace-write` 또는 `danger-full-access`만 허용한다. Windows native sandbox에서 -MSVC compiler-id의 `cl.exe` 정지가 재현되고 동일 명령이 sandbox 밖에서 통과하는 -환경에서는, 해당 실행 직전 사용자 승인을 받은 clean linked Git worktree 실행에 한해서 -`danger-full-access` fallback을 사용할 수 있다. Executor의 -`--approve-danger-full-access` flag도 필요하며 환경변수만으로 승인되지 않는다. -이 override는 등록된 hook을 비활성화하지 않는다. - -Codex에 전달하는 프롬프트는 다음 내용의 조합이다. - -```text -Implementation Agent profile의 역할·수정 경계 -+ AGENTS.md와 docs 문서 -+ 이전에 완료된 Step의 summary -+ 이전 시도의 오류(재시도인 경우) -+ Executor 공통 작업 규칙 -+ 현재 stepN.md -``` - -이전 Step의 전체 대화나 Codex 세션은 전달하지 않는다. task index에 기록한 -`summary`만 다음 Step에 누적한다. - -Codex 실행 결과의 exit code, stdout, stderr는 다음 파일에 저장한다. - -```text -phases/{task-name}/step{N}-output.json -``` - -## 7. 도구 호출 전 PreToolUse 검사 - -[`.codex/hooks.json`](../.codex/hooks.json)은 shell 및 파일 편집 도구에 -[PreToolUse 훅](../scripts/hooks/pre_tool_use.py)을 등록한다. Codex가 실제 명령이나 -편집을 수행하기 전에 이 훅이 요청을 검사한다. - -### 7.1 위험 명령 차단 - -다음 유형의 명령은 요구사항과 관계없이 차단한다. - -- `git reset --hard` -- `git push --force` 또는 `--force-with-lease` -- `rm -rf` -- `Remove-Item -Recurse -Force` -- `rmdir /s /q` -- `DROP TABLE` - -위험 패턴이 발견되면 훅은 차단 이유를 stderr로 출력하고 종료 코드 2를 반환한다. -그러면 해당 도구 호출은 실행되지 않는다. - -### 7.2 C++ TDD 검사 - -`apply_patch`, `Edit`, `MultiEdit`, `Write`로 다음 C/C++ 확장자의 파일을 편집하려 -하면 [TDD 정책](../scripts/msvc_harness/tdd_policy.py)을 검사한다. - -```text -.c .cc .cpp .cxx .h .hpp .hxx -``` - -일반 제품 코드를 수정하려면 대응되는 테스트 파일이 먼저 존재해야 한다. 예를 들어 -`src/calculator.cpp`의 기본 대응 테스트 이름은 다음과 같다. - -```text -calculator_test.cpp -calculator_tests.cpp -test_calculator.cpp -calculator.test.cpp -``` - -테스트는 다음 위치에서 검색한다. - -- `.harness/config.json`의 `tdd.testRoots` -- 제품 파일과 같은 디렉터리 아래 `tests/` -- 제품 파일과 같은 디렉터리 아래 `test/` - -다음 파일과 디렉터리는 대응 테스트 존재 검사가 면제된다. - -- 테스트 파일 자체 -- `main.cpp` -- `.harness/build/**`, `build/**`, `out/**` -- `cmake-build-*/**` -- `third_party/**`, `external/**`, `vendor/**` -- `generated/**` -- `tdd.exclude`에 추가한 경로 - -`tdd.exclude`는 기본 제외 항목을 대체하지 않고 추가한다. - -### 7.3 TDD 검사가 보장하는 범위 - -현재 TDD 훅이 직접 보장하는 것은 대응되는 이름의 테스트 파일이 존재한다는 -사실이다. 다음 항목까지 증명하지는 않는다. - -- 테스트가 이번 요구사항을 실제로 검증하는가 -- 구현 전에 테스트가 실제로 실패했는가 -- 테스트의 assertion과 경계 조건이 충분한가 -- 기존 테스트 파일을 이번 변경과 함께 수정했는가 - -또한 shell 명령의 리다이렉션 등으로 C++ 파일을 쓰는 경우 shell 위험 패턴 검사는 -적용되지만 경로 기반 TDD 검사는 적용되지 않는다. 따라서 이 훅은 완전한 TDD -증명기가 아니라 테스트 우선 편집을 유도하는 guardrail이다. - -PreToolUse는 허용된 편집 도구의 대상 경로를 `.harness/hook-state/`에 기록한다. -이 ignored 기록은 Stop의 문서 전용 판정 입력일 뿐 RED나 실제 편집 성공의 증거가 아니다. - -## 8. Codex 종료 전 Stop 검증 - -Codex가 Step 작업을 끝내고 응답을 종료하려 하면 -[Stop 훅](../scripts/hooks/stop_validation.py)이 실행된다. 유효한 동일 session/turn 기록에서 -편집 대상이 모두 저장소 내부 `.md`이면 build/test를 생략한다. 기록 누락·손상 또는 비문서 -편집이면 정상 검증 경로에서 발견된 C/C++ 프로젝트 전체를 빌드하고 테스트한다. - -Shell 쓰기는 완전히 추적되지 않으며, 편집 기록 없는 읽기 전용 요청도 자동 생략을 -보장하지 않는다. 사용자가 문서 작업의 실행을 제외하면 수동 Hook·build/test를 실행하지 -않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작해 생략을 만들지 않는다. - -### 8.1 저장소 루트와 재진입 방지 - -Stop 훅은 `git rev-parse --show-toplevel`로 프로젝트 루트를 결정한다. Git 저장소를 -찾을 수 없으면 현재 디렉터리를 사용한다. - -빌드나 테스트의 자식 프로세스에는 `CODEX_STOP_VALIDATION_ACTIVE=1`을 전달한다. -같은 훅이 자식 프로세스에서 다시 진입하면 즉시 성공 처리하여 검증 재귀를 막는다. - -### 8.2 설정 로드 - -[설정 로더](../scripts/msvc_harness/config.py)는 `.harness/config.json`을 읽는다. -파일이 없으면 다음 기본값을 사용한다. - -- `version`: 1 -- `projectType`: `auto` -- CMake source: 저장소 루트 -- preset 미사용 시 binary directory: `.harness/build` -- configuration: `Debug` -- platform: `x64` -- 테스트 루트: `tests`, `test` -- 기본 테스트 이름 패턴 네 개 - -설정은 다음 조건을 엄격하게 검사한다. - -- 알 수 없는 필드를 거부한다. -- `version`은 숫자 1만 허용한다. -- `projectType`은 `auto`, `cmake`, `msbuild`만 허용한다. -- 저장소 상대 경로만 허용한다. -- 저장소 밖으로 해석되는 경로를 거부한다. -- CMake preset을 사용하면 `configurePreset`, `buildPreset`, `testPreset`, - `binaryDir`를 모두 요구한다. -- 모든 `tdd.testPatterns`에 `{stem}`을 요구한다. - -### 8.3 프로젝트 자동 감지 - -[프로젝트 탐색기](../scripts/msvc_harness/discovery.py)는 다음 순서로 프로젝트를 -선택한다. - -1. `projectType: cmake` 또는 `projectType: msbuild` 명시 설정 -2. 루트의 `CMakePresets.json` -3. 루트의 `CMakeUserPresets.json` -4. 루트의 `CMakeLists.txt` -5. 루트의 단일 `.sln` -6. 루트의 단일 `.vcxproj` - -자동 감지 결과는 다음처럼 처리한다. - -| 저장소 상태 | 결과 | -|---|---| -| CMake metadata가 있음 | CMake 프로젝트 선택 | -| 하나의 `.sln` 또는 `.vcxproj`가 있음 | MSBuild 프로젝트 선택 | -| 여러 solution/project가 있음 | 설정으로 하나를 지정하라는 오류 | -| C/C++ 파일과 build metadata가 모두 없음 | 검증할 프로젝트가 없으므로 통과 | -| C/C++ 파일은 있지만 build metadata가 없음 | orphan C++ 프로젝트 오류 | - -### 8.4 MSVC 도구 탐색 - -[도구 탐색기](../scripts/msvc_harness/toolchain.py)는 `vswhere.exe`로 다음을 -확인한다. - -- Visual Studio 설치 경로 -- Desktop development with C++ workload -- `MSBuild.exe` - -CMake 프로젝트에서는 다음 우선순위로 CMake와 CTest를 선택한다. - -1. PATH에서 발견한 독립 `cmake.exe`와 `ctest.exe` -2. Visual Studio에 번들된 CMake와 CTest - -따라서 새로 설치한 CMake의 `bin` 디렉터리가 PATH에 반영되어 있으면 독립 CMake를 -우선 사용한다. - -## 9. 빌드 시스템별 검증 계획 - -### 9.1 CMake preset 미사용 - -[CMake adapter](../scripts/msvc_harness/adapters/cmake.py)는 다음 검증 계획을 만든다. - -```powershell -cmake -S -B .harness/build -A x64 -cmake --build .harness/build --config Debug -ctest --test-dir .harness/build -C Debug --show-only=json-v1 -ctest --test-dir .harness/build -C Debug --output-on-failure -``` - -명령 성공 외에 다음 결과도 검사한다. - -- 생성된 CMake compiler metadata의 `CMAKE_CXX_COMPILER_ID`가 `MSVC`인가 -- CTest JSON에 한 개 이상의 테스트가 있는가 - -따라서 빌드가 성공해도 MinGW 등 다른 컴파일러를 사용했거나 CTest가 테스트를 한 -개도 발견하지 못하면 실패한다. - -### 9.2 CMake preset 사용 - -`.harness/config.json`에 preset을 완전히 지정하면 다음 형태로 실행한다. - -```powershell -cmake --preset -cmake --build --preset -ctest --preset --show-only=json-v1 -ctest --preset --output-on-failure -``` - -이 경우 모든 명령은 `cmake.sourceDir`에서 실행하고 compiler metadata 검사는 설정한 -`binaryDir`에서 수행한다. - -### 9.3 직접 MSBuild - -[MSBuild adapter](../scripts/msvc_harness/adapters/msbuild.py)는 다음 순서로 실행한다. - -```powershell -MSBuild.exe /m /nologo ` - /p:Configuration= ` - /p:Platform= - - -``` - -직접 MSBuild 프로젝트는 표준 테스트 탐색 명령이 없으므로 -`.harness/config.json`의 `msbuild.testCommand`가 반드시 필요하다. 이 값이 없으면 -Stop 검증이 실패한다. - -## 10. 명령 실행 안전성과 제한시간 - -[검증 실행기](../scripts/msvc_harness/process.py)는 다음 안전 규칙을 적용한다. - -- 명령을 shell 문자열이 아닌 argv 배열로 실행한다. -- `shell=False`를 사용한다. -- 각 명령의 working directory가 저장소 내부인지 검사한다. -- 명령별 제한시간과 Stop 전체 제한시간 중 더 짧은 값을 적용한다. -- 종료 코드가 0이 아니면 즉시 해당 stage를 실패 처리한다. - -Stop 훅의 전체 제한시간은 저장소 탐색, toolchain 탐색, configure, build, test discovery, -test를 모두 포함해 1,800초다. `.codex/hooks.json`의 Stop command timeout도 1,800초다. - -실패 메시지에는 다음 진단 정보를 포함한다. - -- 실패 stage -- 안전하게 표현한 argv 배열 -- working directory -- 종료 코드 -- stdout과 stderr의 마지막 8,000자 - -Harness는 별도 빌드 로그 파일을 생성하지 않는다. - -## 11. 성공, 실패, 차단 처리 - -### 11.1 Stop 검증 성공 - -빌드와 테스트가 모두 성공하거나 문서 전용 생략 조건을 충족하면 Stop 훅은 출력 없이 -종료한다. 생략은 build/test 통과 evidence가 아니다. Codex가 정상 종료하면 Executor는 -branch/HEAD, 제어 파일과 현재 Step 외 상태의 변경 여부를 검사하고 task index를 읽는다. -Codex 종료 코드가 0이 아니면 `completed` 기록만으로 성공 처리하지 않는다. - -Codex가 Step을 다음처럼 기록한 경우: - -```json -{ - "step": 0, - "name": "division-api", - "status": "completed", - "owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"], - "summary": "divide API와 0 나누기 테스트를 추가함" -} -``` - -Executor는 `completed_at`을 기록하고 변경사항을 커밋한 뒤 다음 `pending` Step을 -실행한다. - -### 11.2 Stop 검증 실패 - -Stop 훅은 Codex hook protocol에 따라 다음 형태의 응답을 출력한다. - -```json -{ - "decision": "block", - "reason": "build failed ..." -} -``` - -훅 자체의 종료 코드는 0이지만 `decision: block`이 종료 차단 이유를 전달한다. -수정은 할당된 역할·Step·retry budget 안에서만 수행하며, Hook 실패가 상위 계약 변경이나 -무제한 반복 권한을 주지 않는다. - -### 11.3 Executor 재시도 - -Executor는 branch/HEAD·제어 파일·결과 형식과 변경 경로의 소유권을 먼저 검증한 뒤 -Step 보고와 프로세스 종료 코드를 함께 판정한다. - -| 결과 | 처리 | 자동 재시도 | -| --- | --- | --- | -| 인식된 sandbox helper 환경 오류(종료 코드 무관), CLI 미설치 | Step과 상위 phase `blocked`, 종료 2 | 없음 | -| 명시적 `blocked` 또는 `error`(종료 코드 무관) | 원래 사유 보존, 각각 종료 2 또는 1 | 없음 | -| `completed` + 종료 0 | 소유권·staged 경로 검증 후 커밋 | 없음 | -| `completed` + nonzero | `error`, 종료 1 | 없음 | -| 결과 미보고 + Executor wrapper의 실제 `TimeoutExpired` | transport timeout | 최초 포함 최대 2회 | -| 결과 미보고 + 종료 0, 원인 미분류 nonzero | `error`, 종료 1 | 없음 | - -종료 코드 124만으로 timeout을 추정하지 않는다. Wrapper가 실제 timeout을 관찰했을 때만 -raw output에 `transportFailure: "timeout"`을 기록한다. 제어·소유권 위반은 이 재시도보다 -우선하여 중단한다. 실패 결과를 `pending`으로 덮어쓰지 않고 원래 보고와 프로세스 진단을 -Executor 소유 history에 구분해 남긴다. - -```text -첫 번째 transport 시도 실패 -→ 오류를 다음 프롬프트에 삽입 -→ 두 번째 독립 Codex 실행 -→ 두 번째도 실패하면 error 기록 후 종료 -``` - -Coordinator의 workflow correction은 별도 budget이다. 정규화된 -`feature_id|failing_gate|failure_classification|contract_revision`별로 Correction을 최대 -한 번, 그 뒤 Implementation rerun을 한 번만 허용한다. 계약·환경·물리 실패를 transport -재시도로 숨기거나 문구만 바꾸어 새 retry key를 만들지 않는다. - -### 11.4 사용자 개입 필요 - -인증, API 키, 수동 설치처럼 Codex가 자동으로 해결할 수 없는 문제가 있으면 Step을 -`blocked`로 기록한다. Executor는 `blocked_at`과 top-level 상태를 갱신하고 종료 코드 -2로 중단한다. - -재개 전 Coordinator가 원인 분류, 실패 evidence, retry key와 허용된 다음 작업을 -`coordination.md`에 보존한다. Coordinator는 phase 파일을 직접 편집하지 않는다. -명시적으로 할당받은 Planning Agent가 Executor가 중단된 상태에서 phase index의 현재 -실패/차단 Step status만 `pending`으로 변경한다. 다른 Step, top-level 상태와 timestamp는 -변경하지 않는다. Executor가 재시작 시 오래된 outcome 필드·timestamp를 정리하되 -`attempt_history`는 유지한다. 기존 Step에 `owned_paths`가 없으면 승인 목록을 작성하는 -별도 Planning 할당이 필요하며 status 복구 권한만으로 목록을 추가·확대하지 않는다. -이는 할당된 파일 편집 절차이며 자동 복구 명령이나 추가 correction 허용이 아니다. - -## 12. Git 커밋과 phase 완료 - -Step이 성공하면 제품 변경과 Harness metadata를 분리해 다음 형식으로 커밋한다. - -```text -feat(add-division): step 0 - division-api -chore(add-division): step 0 output -``` - -두 번째 커밋의 `output`은 task index의 Step 상태와 summary 같은 Harness metadata를 -뜻한다. 원시 Codex 실행 기록인 `stepN-output.json`은 `.gitignore` 대상이며 커밋에 -포함되지 않는다. - -모든 Step이 완료되면 Executor는 다음 작업을 수행한다. - -- task의 `completed_at` 기록 -- `phases/index.json`의 task 상태를 `completed`로 변경 -- 최종 metadata 커밋 -- `--push` 사용 시 `origin/feat-{phase-name}`으로 push - -Executor는 신뢰된 `owned_paths` snapshot으로 매 시도 후와 staging 직전의 변경 경로를 -검사한다. tracked/untracked, staged/unstaged, 생성·수정·삭제와 rename 양쪽 경로가 대상이다. -Windows 경로 구분자·대소문자 alias를 정규화하며 디렉터리·링크 대체도 다시 검사한다. -범위 밖 변경이 있으면 index를 정리하기 전에 중단하고 해당 경로와 사용자 파일을 보존한다. - -검사 후 검증된 경로 snapshot에 한정해 index만 정리하고 -`git --literal-pathspecs add -A -- <선택 경로>`를 사용한다. 저장소 전체 index를 reset하지 않는다. -Commit 직전에는 `git diff --cached --name-only --no-renames -z`의 실제 staged 경로도 -선택된 커밋 그룹과 대조한다. 구현 커밋에 phase metadata가 섞이는 것도 거부한다. -범위 위반 시 추가 stage/commit·재시도·다음 Step을 중단하며 파일을 되돌리거나 allowlist를 -자동 확대하지 않는다. staging 후 발견한 위반은 당시 index를 남기므로 재개 전 검토가 필요하다. - -동시 writer에 대한 원자적 격리는 보장하지 않으므로 실행 중 동시 편집을 피한다. 구현·metadata -커밋도 단일 transaction이 아니다. 구현 커밋 후 metadata 커밋이 실패하면 기존 커밋을 -되돌리지 않고 Step을 `error`로 기록해 Coordinator에 반환한다. - -## 13. 요구사항 종류별 동작 - -| 받은 요구사항 또는 변경 | PreToolUse 동작 | Stop 동작 | -|---|---|---| -| 새 C++ 제품 파일 추가 | 대응 테스트가 먼저 없으면 차단 | 전체 빌드·테스트 | -| 기존 C++ 구현 또는 header 수정 | 대응 테스트 파일 존재 여부 검사 | 전체 빌드·테스트 | -| 테스트 파일 추가 | TDD 차단 없이 허용 | 모든 테스트가 성공해야 종료 | -| `main.cpp` 수정 | TDD 대응 테스트 검사 면제 | 전체 빌드·테스트 | -| 유효한 동일 session/turn 기록의 내부 `.md` 편집만 있음 | C++ TDD 검사 없이 경로 기록 | build/test 생략, 통과 evidence 아님 | -| JSON, Python 또는 다른 비문서 편집 | C++ TDD 검사 없음 | C++ 프로젝트가 있으면 전체 검증 | -| 편집 기록 없음·손상 또는 shell 쓰기 | 완전한 편집 추적을 보장하지 않음 | 문서 전용 자동 생략을 보장하지 않음 | -| 위험한 Git 또는 삭제 명령 | 즉시 차단 | 도달하지 않음 | -| C++ 파일은 있지만 build metadata 없음 | 편집은 허용될 수 있음 | orphan 프로젝트 오류 | -| 직접 MSBuild인데 `testCommand` 없음 | 편집은 허용될 수 있음 | 설정 오류로 종료 차단 | -| C/C++가 전혀 없는 저장소 | 관련 편집 검사 없음 | 검증할 프로젝트가 없어 통과 | - -## 14. 적용 전 준비사항 - -FESA는 실제 구조해석 솔버 프로젝트이며 Harness는 재사용 가능한 개발 운영 인프라다. -일반 Feature 실행 전에 다음을 확인한다. - -1. `AGENTS.md`, 공통 PRD·ARCHITECTURE·ADR와 승인된 Feature 범위를 읽는다. -2. Feature 관리 문서·선행 계약·revision과 Planning/Implementation dispatch를 확인한다. - 일반 Feature 작업에서 프로젝트 공통 문서를 템플릿처럼 다시 작성하지 않는다. -3. 기본 자동 감지로 충분하지 않을 때만 `.harness/config.example.json`을 참고해 - `.harness/config.json`을 만든다. -4. FESA의 CMake/MSVC x64 Debug·CTest 명령과 dependency 경로를 확인한다. 다른 저장소에 - Harness를 적용할 때만 그 프로젝트의 승인된 adapter를 선택한다. -5. phase 파일이 없다면 Planning Agent가 할당된 파일을 작성한다. 실행 권한은 별도로 확인한다. -6. 시작 전 clean 범위와 실행 중 동시 편집 여부를 확인한다. 권한 상승은 clean linked - worktree, native sandbox 실패 증거와 해당 실행 직전 승인·flag가 모두 필요하다. - -특히 `AGENTS.md`와 `docs/*.md`는 각 Codex 실행에 그대로 주입된다. C++ 프로젝트에서 -TypeScript 예시나 미완성 placeholder가 남아 있으면 실제 작업 지시와 충돌할 수 있다. +옛 phase/push/권한 상승 CLI와 legacy `tdd` 설정의 처리는 +[이전 운영 방식 안내](HARNESS.md#이전-운영-방식에서-달라진-점)를 따른다. +사용자 config와 이력을 자동 migration하거나 실패 evidence를 지우지 않는다. +로컬 검증은 commit·push·tag·release 또는 외부 solver 실행 권한을 부여하지 않는다. diff --git a/docs/PRD.md b/docs/PRD.md index bf2a08f..9c18f64 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -41,15 +41,15 @@ Harness와 agent·skill은 이 목표를 달성하기 위한 개발 운영 인 | 이 PRD | 제품 목적, 공통 요구사항, 품질 속성과 완료 기준 | | [ARCHITECTURE](ARCHITECTURE.md) | 공통 책임, 의존성, 수명과 확장 경계 | | [ADR](ADR.md) | 프로젝트 전반의 설계 결정과 변경 이력 | -| Feature `PRD.md` | 해당 요구의 목적·범위·제외·acceptance 요약과 상세 요구사항 링크 | -| Feature `requirements.md` | Requirement Agent가 소유하는 검증 가능한 요구사항과 verification matrix | +| Feature `PRD.md` | 목적·범위·제외, 작은 요구사항·acceptance의 원본, 현재 checklist와 상세 계약 링크 | +| Feature `requirements.md` | 복잡한 요구사항을 분리할 때만 작성하는 상세 요구사항과 verification matrix | | Feature `ADR.md` | 해당 Feature의 결정·이유·영향·owner와 승인 근거 | | Feature 전문 산출물 | 연구, 정식화, 수치/reference 검토, I/O, 구현·검증, 물리 검토와 release evidence | -Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분리는 -[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. Feature PRD가 -`requirements.md`와 별도의 요구사항 원본을 만들거나 공통 기준을 묵시적으로 덮어쓰지 않는다. -공통 기준 자체의 변경은 별도로 승인된 프로젝트 문서 작업으로 다룬다. +Feature 문서의 생성·재개, 메인이 관리하는 핵심 문서 3개와 선택적 상세 문서는 +[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 작은 요구사항은 Feature +PRD에 정의하고, 상세 요구사항을 분리하면 PRD에는 요약과 링크만 남겨 원본을 중복하지 않는다. +공통 기준을 묵시적으로 덮어쓰지 않으며 기준 자체의 변경은 별도로 승인된 문서 작업으로 다룬다. ## 공통 기능 요구사항 @@ -69,9 +69,9 @@ Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분 | FESA-PRD-GEN-007 | 결과의 물리량, location, units, coordinates, component, entity와 step/frame 의미를 식별할 수 있어야 한다. | I/O·result schema 계약과 mapping 검증 | | FESA-PRD-GEN-008 | 실패한 candidate가 유효한 state나 최종 결과를 부분적으로 오염시키지 않도록 계약된 보존 범위를 지켜야 한다. | State commit·복구·출력 실패 검증 | | FESA-PRD-GEN-009 | 외부 형식과 vendor/OS API를 adapter 뒤에 격리하고 solver core에 노출하지 않아야 한다. | Public dependency와 adapter 경계 검토 | -| FESA-PRD-GEN-010 | Production 동작 변경은 관련 테스트의 기대 실패를 관찰한 뒤 구현하고 지정된 검증 evidence를 남겨야 한다. | RED/GREEN, focused/full 검증 명령과 실제 결과 | +| FESA-PRD-GEN-010 | Production 동작 변경은 해당 동작을 확인하는 테스트로 검증하고, 버그는 가능한 경우 실패를 재현한 뒤 최소 수정해야 한다. | 변경 영향에 맞는 검사, 가능한 버그 재현, 기능 완료 시 전체 검증 명령과 실제 결과 | | FESA-PRD-GEN-011 | 기능에 필요한 독립 검증과 reference 비교를 수행하고 승인된 identity·수치 정책을 유지해야 한다. | 검증 matrix, 사전검사, reference 또는 명시적 N/A와 대체 근거 | -| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 요구사항부터 물리 검토·release readiness까지의 gate 기록 | +| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 해당 계약을 지지하는 검증 결과, 적용 범위·제한과 미해결 항목 | 요구사항 단계는 acceptance intent와 필요한 물리적 관찰을 정한다. Numerical Review는 기존 승인 정책 안에서 논리적 비교량·identity/component·판정 구분을 구체화하고, I/O는 이를 @@ -109,19 +109,22 @@ unit, analytical/benchmark, integration, convergence, invariant 및 외부 refer - 실패·미실행·stale evidence를 통과로 표시하지 않는다. 과거 통과 기록을 현재 검증으로 소급 적용하지 않는다. -정규 Feature workflow는 다음과 같다. +메인 assistant가 범위를 파악하고 필요한 전문 작업을 선택하여 구현·검증·결과 확인을 +조정한다. 수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review와 +해당 analytical/invariant 검증을 수행한다. 필요한 물리 검토와 reference 비교도 유지한다. -`requirements → research → formulation → numerical-review → io-definition → -implementation-planning → implementation → physics-evaluation → release-readiness` +변경 중에는 관련 검사를 수행하고, 솔버 기능 완료 시 구성된 전체 build/test와 계약상 필수 +reference 비교를 한 번 수행한다. 요청되거나 영향이 넓어 전체 검증이 필요한 경우에도 +실행한다. 이후 변경·실패가 없으면 같은 검증을 반복하지 않는다. 기존 coverage가 충분한 +rename/refactor에는 형식적인 새 테스트를 요구하지 않는다. -구현 gate는 TDD, 지정된 전체 build/test와 필수 reference evidence가 갖추어졌을 때 -통과한다. Feature closure에는 그 뒤의 독립 물리 검토와 release-readiness 감사도 필요하다. -Release readiness는 내부 완료 권고이며 외부 publish, push, tag, deploy 또는 package 권한이 아니다. +Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다. Readiness 권고는 +외부 publish, push, tag, deploy 또는 package 권한이 아니다. 메인은 필수 evidence와 +미해결 항목을 확인하여 완료 여부를 판단하며, 문서 수정에는 정적 검토를 적용한다. -Owner, 공통 handoff, outcome, stale 처리와 유한 correction은 +현재 운영 결정은 [ADR-028](ADR.md#adr-028), 역할과 인계·실패 처리는 [SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md)을 따른다. Skill의 적용 경계는 [SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md), 실행 절차는 각 현재 `SKILL.md`를 따른다. -문서만 수정하는 작업을 solver Feature 전체 workflow로 확대하지 않는다. ## 단계적 확장과 비목표 diff --git a/docs/SOLVER_AGENT_DESIGN.md b/docs/SOLVER_AGENT_DESIGN.md index 608c8b2..395bb5e 100644 --- a/docs/SOLVER_AGENT_DESIGN.md +++ b/docs/SOLVER_AGENT_DESIGN.md @@ -1,220 +1,135 @@ # Structural FEM Solver Agent Design -## 1. 목적 +## 목적 -이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다. -`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과 -산출물만 소유한다. 기능별 문서는 `docs//`에 보존한다. -폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는 -[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다. +메인 assistant가 작업 분해, 필요한 specialist 선택, 구현 조정과 완료 확인을 담당한다. +작은 문서·구현·일상 결함은 직접 처리한다. Specialist는 전문 판단이나 독립 검토가 +필요한 bounded task에 사용하며 고정 lifecycle을 순회하기 위해 호출하지 않는다. -이 계약의 목표는 다음과 같다. +현재 운영 결정은 [ADR-028](ADR.md#adr-028), Feature 폴더와 산출물 관리는 +[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 필요한 계약과 검증은 +유지하면서 문맥 재독, 형식적 인계와 같은 결과의 반복 검토를 줄인다. -- 수치적·물리적 책임을 명확히 분리한다. -- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다. -- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다. -- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다. -- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다. - -## 2. 권한과 판단 기준 +## 권한과 판단 기준 충돌하는 정보는 다음 우선순위로 판단한다. -1. 사용자가 승인한 feature contract와 critical decision -2. 지배 방정식, 수학적 일관성, 적용되는 표준과 검증된 1차 문헌 -3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 verification 사례 -4. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md`와 기존 승인 계약 +1. 현재 사용자 요청의 범위·권한과 승인된 Feature contract·critical decision +2. 지배 방정식, 수학적 일관성, 적용 표준과 검증된 1차 문헌 +3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 검증 사례 +4. 프로젝트 지침, architecture, ADR, tolerance와 기존 승인 계약 5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현 -Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석 -절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료 -구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다. -관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다. +Abaqus는 외부 reference convention이다. 지원 subset의 공개 입력 의미와 승인된 비교량을 +참고하되 비공개 알고리즘·내부 상태·결과 생성 절차를 추정하거나 내부 동등성을 주장하지 +않는다. 수치 결과의 exact equality는 허용되지만 내부 동등성의 evidence가 아니다. +의미상 무해하다고 계약된 항목만 명시적 warning/no-op으로 처리하고 그 밖의 미지원 +semantics는 fail-closed로 진단한다. -공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이 -입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로 -진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다. +## 메인의 작업 조정 -## 3. 계층과 단독 상태 전이 +메인은 관련 계약과 현재 evidence를 확인하여 작업·수정 파일·검증 기준을 정한다. +새 Feature에 지속할 계약이나 근거가 필요하면 `docs//`를 초기화하고 +`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 작은 수정에는 새 Feature 폴더나 +빈 보고서를 만들지 않는다. 현재 checklist는 PRD 한 곳에 둔다. -`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다. +메인은 계획·구현·일반 실패 수정을 직접 수행하거나 필요한 구현 묶음을 위임할 수 있다. +Specialist는 할당된 판단과 파일만 소유하며 다른 계약을 수정하거나 peer를 재위임하지 +않는다. 메인은 결과를 확인하되 독립 검토가 필요한 판단을 작성자의 자기 승인으로 대체하지 +않는다. 누락된 evidence는 통과가 아니다. -```text -INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD -``` +## Specialist 선택 -- Coordinator는 요구사항 접수 시 Feature 폴더와 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, - `coordination.md`를 생성하고 문서 목록과 참조를 관리한다. 프로젝트 기준 문서는 보존한다. -- Coordinator만 `docs//coordination.md`의 현재 stage, outcome과 next owner를 바꾼다. -- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다. -- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다. -- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한 - 후 기록한다. -- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다. -- 누락된 증거는 통과로 간주하지 않는다. +현재 profile은 [`.codex/agents`](../.codex/agents)에 있다. -## 4. 단계와 소유권 - -| Stage | Owner | Owned outputs | +| Specialist | 호출할 때 | 기본 추론 강도 | | --- | --- | --- | -| intake / coordination | `coordinator-agent` | `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md` | -| `requirements` | `requirement-agent` | `requirements.md` | -| `research` | `research-agent` | `research.md` | -| `formulation` | `formulation-agent` | `formulation.md` | -| `numerical-review` | `numerical-review-agent` | `numerical-review.md`, `reference-model.md` | -| `io-definition` | `io-definition-agent` | `io.md` | -| `implementation-planning` | `implementation-planning-agent` | `implementation-plan.md`, assigned Harness phase files | -| `implementation` | `implementation-agent` | implementation files, tests, build registration, `implementation-report.md`, `build-test.md`, `reference-comparison.md` | -| `physics-evaluation` | `physics-evaluation-agent` | `physics-evaluation.md` | -| `release-readiness` | `release-agent` | `release.md` | +| `requirement-agent` | 범위·acceptance가 복잡하거나 상충하여 별도 계약 정리가 필요 | `medium` | +| `research-agent` | 사용할 이론·benchmark·reference 근거가 부족 | `medium` | +| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화가 필요 | `high` | +| `numerical-review-agent` | 새 정식화·주요 수치 변경·원인 불명의 수치 불일치를 독립 검토 | `high` | +| `io-definition-agent` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경 | `medium` | +| `implementation-agent` | 메인이 직접 수행하기보다 위임할 이점이 있는 구현 묶음 | `medium` | +| `physics-evaluation-agent` | 새 해석 기능이나 결과의 평형·물리적 타당성·coverage 평가가 필요 | `high` | -`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만 -implementation-owned 파일과 `corrections.md`를 수정한다. +수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review를 수행한다. +역할의 조건부 호출은 해당 analytical/invariant 검증이나 계약상 필수 물리·reference +검증을 생략할 근거가 아니다. Release-readiness 감사는 사용자 명시 요청 시에만 +`fem-release-readiness`로 수행하며 전용 release profile이나 필수 종료 stage를 두지 않는다. -문서 경로는 모두 `docs//` 기준이다. 각 specialist는 자신의 기본 산출물에 -연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며 -specialist 본문의 편집 권한을 뜻하지 않는다. +모델과 역할별 강도는 현재 profile을 따른다. 난해한 정식화·수렴 문제에만 필요한 범위에서 +강도를 높인다. Profile 변경만으로 이미 실행 중인 session의 설정이 갱신되었다고 가정하지 +않는다. 불필요한 진행 확인·보고서 재작성·같은 결과의 재검토를 위해 agent를 호출하지 않는다. -각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나 -재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한 -`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다. +## 작업 인계와 반환 -## 5. 공통 handoff envelope +Dispatch에는 다음 정보만 필요한 만큼 전달한다. -모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고 -envelope에는 전이에 필요한 요약만 둔다. +- 수행할 작업과 결정할 문제 +- 관련 계약·원문의 경로와 절, 필요한 Feature context +- 수정할 정확한 파일과 제외 범위 +- 검증 기준과 완료에 필요한 evidence -```yaml -feature_id: -stage: requirements | research | formulation | numerical-review | io-definition | - implementation-planning | implementation | correction | physics-evaluation | - release-readiness -outcome: pass | return-upstream | retry | blocked-environment | needs-user-decision -next_owner: -evidence_paths: [] -evidence_digest: -failure_classification: -retry_key: -attempt: -escalation_class: -blocker: -``` +새 agent는 도구가 지원하면 `fork_turns="none"`으로 시작하여 필요한 문맥만 전달한다. +연속 수정은 기존 agent에 짧은 후속 작업으로 보낸다. 같은 문맥에서 읽은 변경 없는 자료를 +다시 읽거나 모든 Feature 문서를 매번 주입하지 않는다. -필드 규칙은 다음과 같다. +Return은 결과·판단, 변경 파일, 실행한 명령·exit code·결정적 결과, 미해결 항목·제한을 +간결하게 전달한다. 고정 envelope, outcome enum, retry signature나 artifact hash를 모든 +작업에 요구하지 않는다. 추적에 필요한 계약 revision과 실제 evidence 경로는 남기고, +긴 로그·유도·schema는 원본을 연결한다. -- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다. -- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다. -- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다. -- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다. -- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다. -- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다. -- Dispatch는 `docs//`와 Feature 관리 문서 3개를 필수 입력으로 명시한다. - 기본·상세 산출물의 owner를 지정하고 반환된 상세 문서도 `evidence_paths`로 확인한다. +## 구현·검증과 완료 -## 6. Outcome과 전이 규칙 +동작 변경에는 그 동작을 확인하는 테스트를 추가·수정하고, 버그는 가능한 경우 실패를 +재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor나 문서 수정에는 +형식적인 새 테스트를 요구하지 않는다. -| Outcome | 의미 | Coordinator action | -| --- | --- | --- | -| `pass` | 현재 owner의 gate evidence가 완전함 | 다음 정규 stage로 전이 | -| `return-upstream` | 선행 계약의 수정이 필요함 | `next_owner`로 되돌리고 영향받은 downstream gate를 stale 처리 | -| `retry` | 계약을 바꾸지 않는 bounded rerun이 가능함 | retry 정책 안에서 지정 owner를 재호출 | -| `blocked-environment` | 도구·권한·의존성·라이선스 문제로 신뢰성 있는 진행 불가 | 상태를 보존하고 환경 수정 전까지 중단 | -| `needs-user-decision` | 아래 critical decision이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 | +변경 중에는 관련 검사를 실행한다. 솔버 기능 완료 시, 사용자가 요청한 경우 또는 영향이 +넓어 필요한 경우 구성된 전체 build/test를 한 번 수행한다. 기능 완료에 필요한 reference +비교도 수행하며 이후 변경·실패가 없으면 같은 검사를 반복하지 않는다. 문서 작업은 정적 +검토로 확인하고 build/test를 실행하지 않는다. -`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지 -않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만 -사용한다. +메인은 완료를 판단할 때 다음을 확인한다. -정규 통과 순서는 다음과 같다. +- 해당 요구와 계약을 지지하는 실제 결과가 있고 stale/missing evidence가 아님 +- 수치 변경에 필요한 독립 검토, analytical/invariant와 물리 검증이 있음 +- Reference quantity, unit, coordinate/component와 source identity가 대응함 +- Missing, extra, duplicate와 nonfinite required value를 tolerance 전에 거부함 +- [TOLERANCE](TOLERANCE.md)와 승인된 Feature 판정 기준을 유지함 +- 실제 명령·exit code·판정값과 가정·미지원 범위·잔여 위험을 재현 가능하게 기록함 -```text -requirements -> research -> formulation -> numerical-review -> io-definition --> implementation-planning -> implementation -> physics-evaluation --> release-readiness -> completed -``` +Reference artifact와 상위 계약을 구현 결과에 맞춰 생성·보정하거나 tolerance를 완화하지 +않는다. 실패·미실행 검사를 통과로 표시하지 않으며 과거 통과를 현재 검증으로 소급하지 않는다. -Numerical review는 formulation correctness와 reference-model readiness가 모두 확보되어야 -`pass`할 수 있다. Implementation은 TDD evidence, 전체 build/test와 feature가 요구하는 -reference comparison이 모두 통과해야 `pass`할 수 있다. Release의 `pass`는 내부 readiness -closure일 뿐 publish, deploy, push, tag 또는 package 권한이 아니다. +## 실패 처리와 사용자 결정 -## 7. 자율 진행과 사용자 escalation +일반 구현 실패는 현재 구현 owner가 재현·수정하고 관련 검사를 수행한다. 새 근거나 변경 +없이 같은 명령·agent 호출을 반복하지 않는다. 다른 관점이 필요할 때만 원인과 관련 evidence를 +전문가에게 전달한다. 고정 correction 횟수나 transport 재시도 예산을 두지 않는다. -Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다. +상위 계약 결함은 정확한 계약 owner와 경로를 메인에 알린다. Downstream이 요구사항·수식· +schema·tolerance·reference를 바꾸어 실패를 숨기지 않는다. 실제 계약 변경은 영향받은 +evidence를 다시 확인하고, 환경 문제는 필요한 환경 변화와 재개 조건을 기록한다. -- 승인 계약을 구현하는 파일 배치, private API와 내부 자료구조 선택 -- 기존 규칙에 따른 테스트 분해, config-selected build/test backend 등록, 진단 문구와 오류 처리 -- 문서·계획·evidence report의 생성 및 갱신 -- 명백한 compile, link, test, parser와 implementation defect의 최소 수정 -- Numerical Review가 `docs/TOLERANCE.md`와 feature evidence에 따라 선택하는 비교 quantity, - identity/component, metric, scale, blocking/diagnostic 구분과 수치 tolerance -- 공식 문서와 저장소 관례가 하나의 의미를 정하는 secondary convention -- 안전한 read-only 조사, local build/test와 저장된 reference artifact 비교 +승인된 범위 안의 되돌릴 수 있는 저장소 작업에는 반복적인 중간 승인 절차를 추가하지 않는다. +계획 요청만으로 실행 권한을 추정하지 않으며 다음 결정이 실제로 필요할 때 사용자에게 +대안·권고·영향을 함께 제시한다. -다음 항목만 `needs-user-decision`으로 escalation한다. +- 지원 physics·제품 범위·공개 호환성의 변경 +- 지배 방정식·정식화·재료 모델 등 물리적 의미의 선택 +- 합격/불합격이나 공개 정확도 약속을 바꾸는 acceptance·tolerance 선택 +- Authoritative 입력·영속 결과 schema의 비호환 변경이나 해결되지 않은 필수 계약/reference 충돌 +- 외부 solver의 라이선스·자격증명·비공개 자료·비용 또는 외부 협조 +- 중대한 보안·신뢰 경계 변경이나 해결되지 않은 보안·법률·라이선스 위험 수용 +- 파괴적 Git/파일 작업, push·tag·publish·deploy·package·release -- feature scope, 지원 해석 유형 또는 공개 호환성의 변경 -- 지배 방정식, 요소 정식화, 재료 모델, 접촉·동역학 등 물리적 의미의 선택 -- 합리적인 두 acceptance 기준이 동일 evidence를 pass와 fail로 나누고 그 선택이 제품 - acceptance 의미나 공개 정확도 약속을 바꾸는 경우 -- authoritative input/output schema나 영속 public contract의 비호환 변경 -- authoritative requirement와 reference evidence가 충돌하고 기술 evidence로 우선순위를 - 결정할 수 없는 경우 -- 외부 solver 실행에 필요한 라이선스·자격증명·비공개 자료 -- 보안·신뢰 경계 또는 credential 처리의 중대한 변경, 해결되지 않은 보안·법률·라이선스 - 위험의 수용 -- destructive Git 작업, 외부 게시, push, tag, deploy, package 또는 release +내부 검증 또는 readiness 권고는 외부 실행 권한이 아니다. 이미 승인된 작업의 일반 문서 +작성·로컬 실행·인계마다 승인을 다시 요구하지 않는다. -질문은 결정 가능한 대안, downstream 영향과 권고안을 하나로 묶는다. 단순 진행 확인, -일반 문서 승인, 계획 승인 또는 agent 간 handoff 승인을 반복해서 요청하지 않는다. +## 언어와 기록 -## 8. 실패 분류와 유한 correction - -실패 분류는 최소한 다음 값을 정규화해 사용한다. - -```text -configure | compile | link | test | reference-comparison | harness | -environment | upstream-contract | physics | evidence -``` - -Coordinator는 다음 요소로 retry signature를 만든다. - -```text -retry_key = feature_id | failing_gate | normalized_failure_classification | contract_revision -``` - -동일 `retry_key`에 대한 Correction loop는 한 번만 허용한다. - -1. Implementation Agent가 실패를 분류하고 명백한 implementation-owned defect를 최소 수정·재검증한다. -2. 반복되거나 원인이 불명확하면 Coordinator가 해당 key의 correction 사용 이력을 확인한다. -3. 사용 이력이 없을 때만 Correction Agent를 한 번 dispatch한다. -4. Correction Agent는 `retry`로 Implementation rerun을 요청하고 Coordinator가 rerun을 dispatch한다. -5. 같은 key가 다시 실패하면 두 번째 correction을 금지한다. 계약 문제는 `return-upstream`, - 환경 문제는 `blocked-environment`, 실제 critical choice만 `needs-user-decision`으로 전환한다. - -문구만 바꾸거나 동일 계약 revision을 새 key로 가장하면 안 된다. Upstream 계약이 승인된 방식으로 -변경된 경우에만 `contract_revision`을 올리고 새 signature를 만든다. - -## 9. Evidence gate - -Coordinator는 `pass` 전에 다음을 확인한다. - -- 요구되는 산출물이 존재하고 owner가 명시되어 있다. -- 선행 artifact와 revision이 일치하며 stale evidence가 아니다. -- 실행 증거에는 실제 명령, 종료 코드, 핵심 결과가 있다. -- 수치 비교에는 quantity, unit, coordinate/component, matching rule과 적용 tolerance가 있다. -- reference row의 missing, extra, duplicate와 nonfinite 값은 tolerance 판정 전에 검출된다. -- 가정, 미지원 범위와 잔여 위험이 기록되어 있다. -- specialist owner의 결론을 Coordinator나 downstream agent가 대신 만들지 않았다. -- Feature 문서 목록과 기본·상세 문서 링크가 유효하고 필수 상세 근거까지 검토되었다. - -Reference input과 결과 artifact는 명시적으로 소유 agent가 아닌 한 read-only다. 저장된 외부 -reference 결과를 임의로 생성·보정하거나 통과하도록 수치를 변경해서는 안 된다. - -## 10. 언어와 기록 - -- 기능 문서는 사용자가 다른 언어를 요청하지 않는 한 한국어 Markdown으로 작성한다. -- Agent id, field name, outcome, failure classification, requirement id, path와 command는 English를 유지한다. -- Requirement id 기본 형식은 `FEM-REQ--###`이다. -- Placeholder artifact는 만들지 않는다. Correction이 실제 발생할 때만 `corrections.md`를 만든다. -- 모든 stage는 자신이 변경한 경로와 변경하지 않은 upstream contract를 명확히 기록한다. +기능 문서는 기본적으로 한국어 Markdown으로 작성한다. Agent/skill ID, field, +requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 +`FEM-REQ--###`이다. 보고서는 실제 결정과 evidence를 한 번만 기록하고, +기존 phase·coordination·실패 기록은 이력으로 보존한다. diff --git a/docs/SOLVER_SKILL_DESIGN.md b/docs/SOLVER_SKILL_DESIGN.md index 136031c..67dee63 100644 --- a/docs/SOLVER_SKILL_DESIGN.md +++ b/docs/SOLVER_SKILL_DESIGN.md @@ -1,165 +1,92 @@ # Structural FEM Solver Skill Design -## 1. 목적 +## 목적과 적용 원칙 -Project-local skill은 범용 유한요소 구조해석 solver feature를 요구사항부터 release readiness까지 -일관되게 처리하는 재사용 절차다. Agent가 stage의 책임과 write boundary를 소유하고, skill은 -그 stage에서 필요한 판단 방법, evidence와 output contract를 제공한다. +Project-local skill은 필요한 FEM 판단과 검증 방법을 제공한다. 고정 lifecycle의 모든 +skill을 순회하지 않는다. 메인 assistant 또는 할당된 specialist는 현재 작업에 필요한 +skill과 직접 영향받는 계약만 읽는다. -실행 지침의 source of truth는 각 `.codex/skills//SKILL.md`다. 공통 workflow와 -상태 전이는 `docs/SOLVER_AGENT_DESIGN.md`, 수치 비교 정책은 `docs/TOLERANCE.md`가 소유한다. -Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다. +실행 지침의 원본은 각 `SKILL.md`다. 역할·인계는 +[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), 공통 운영 결정은 +[ADR-028](ADR.md#adr-028), 수치 비교 정책은 [TOLERANCE](TOLERANCE.md)를 따른다. -## 2. 설계 원칙 +- 이름과 description은 실제 사용할 조건을 구분한다. +- `SKILL.md`에는 목적·필요 입력·판단 규칙·결과·수정 경계를 둔다. +- 긴 유도나 toolchain·해석 계열별 절차는 `references/`에서 필요할 때만 읽는다. +- 같은 문맥에서 읽은 변경 없는 자료를 재독하거나 모든 Feature 문서를 인계에 넣지 않는다. +- Skill은 승인된 작업 범위나 외부 실행 권한을 넓히지 않는다. +- FESA가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 수치 계약은 유지한다. +- 필요한 산출물만 [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 작성한다. + 빈 보고서, 고정 envelope·outcome, 자동 commit이나 workflow 상태 파일을 요구하지 않는다. -- 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다. -- `SKILL.md`에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다. -- 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 `references/`에서 필요한 - 경우에만 읽는다. -- Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다. -- 산출물은 Coordinator가 생성·관리하는 `docs//`의 공통 feature bundle에 둔다. -- [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 핵심 결과만 본문에 두고 필요한 - 상세 내용은 같은 폴더의 별도 문서로 분리해 참조한다. Feature 관리 문서에서 공통 기준과 - 현재 작업을 연결하며 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 보존한다. -- 모든 stage는 공통 handoff envelope와 다섯 outcome을 사용한다. -- Input, result container, tabular comparison format, compiler와 build adapter는 project/feature - contract가 선택한다. 특정 형식을 solver identity로 고정하지 않는다. -- Read-only 조사와 reversible in-repository 판단은 자율 수행한다. Critical decision만 - `needs-user-decision`으로 반환한다. +## FEM skill inventory -## 3. Workflow skill inventory +다음 8개 skill은 [`.codex/skills`](../.codex/skills)에 있다. 대표 산출물은 필요한 +경우의 예시이며 모든 작업에 별도 파일을 생성하라는 요구가 아니다. -| Stage | Skill | 대표 산출물 | +| Skill | 사용할 때와 필요한 입력 | 결과와 경계 | | --- | --- | --- | -| Requirements | `fem-requirements-baseline` | `requirements.md` | -| Research | `fem-research-evidence` | `research.md` | -| Formulation | `fem-formulation-spec` | `formulation.md` | -| Numerical review | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` | -| I/O definition | `fem-io-contract` | `io.md` | -| Planning/implementation/correction | `fem-implementation-tdd` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md`, 필요 시 `corrections.md` | -| Physics evaluation | `fem-physics-review` | `physics-evaluation.md` | -| Release readiness | `fem-release-readiness` | `release.md` | +| `fem-requirements-baseline` | 지속할 scope·acceptance 계약이 필요할 때 사용자 요구와 관련 기존 계약 확인 | 검증 가능한 요구·acceptance; 복잡하면 `requirements.md`와 matrix로 분리. 수식·schema·수치 기준을 선결정하지 않음 | +| `fem-research-evidence` | 이론·benchmark 근거가 부족할 때 구체적인 solver 질문과 관련 원문 확인 | 출처 있는 연구 근거·적용 한계·gap. 사실과 추론을 구분하고 정식화 결론을 대신하지 않음 | +| `fem-formulation-spec` | 새 수학 모델이나 변경된 정식화가 필요할 때 관련 요구·근거 확인 | DOF/kinematics, residual/tangent, integration, state update와 recovery 계약. 구현이나 자기 승인을 하지 않음 | +| `fem-numerical-review` | 정식화·안정성·검증 범위의 독립 검토가 필요할 때 수식과 evidence 확인 | 수치 위험·analytical/invariant 검증·reference-model 준비 판단. 비교량·identity·location·units를 정의하고 저장 layout은 I/O에 남김 | +| `fem-io-contract` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경될 때 관련 계약 확인 | 지원 subset, fail-closed 진단, 결과 의미와 저장·비교 mapping. 공개 compatibility를 임의 확대하지 않음 | +| `fem-implementation-tdd` | 솔버 계획·구현·수정 시 할당 작업, 영향받는 계약과 build 설정 확인 | 최소 코드·의미 있는 테스트·필요한 계획과 검증 evidence. 상위 계약·reference·tolerance를 결과에 맞추어 수정하지 않음 | +| `fem-physics-review` | 결과의 평형·부호·대칭·energy·mode·coverage 평가가 필요할 때 결과와 승인 기준 확인 | 물리적 타당성과 적용 한계. 새 acceptance를 즉석에서 만들거나 코드·계약을 수정하지 않음 | +| `fem-release-readiness` | 사용자가 release-readiness 감사를 명시 요청할 때 해당 Feature 계약·결과·제한 확인 | 필수 evidence와 잔여 위험에 대한 내부 권고. 필수 lifecycle stage나 외부 release 권한이 아님 | -위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter `name`, agent prompt와 -`agents/openai.yaml` invocation name은 항상 동일해야 한다. +수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 해당 analytical/invariant +검증은 유지한다. 메인은 `fem-implementation-tdd`를 직접 사용하여 계획·구현·일반 실패 +수정을 수행할 수 있다. 별도 planning/correction profile이나 Harness phase 파일이 필요하지 않다. -## 4. Stage별 책임 분리 +## Supporting skill -### Requirements - -`fem-requirements-baseline`은 scope, observable requirement, acceptance intent와 -requirement-verification matrix를 정의한다. Formulation, tolerance 값, API와 storage schema를 -선결정하지 않는다. - -### Research - -`fem-research-evidence`는 governing theory, primary source, benchmark와 reference convention의 -신뢰성·적용 한계를 정리한다. 사실, 계산, 추론과 evidence gap을 구분하며 formulation 결론을 -대신 만들지 않는다. - -### Formulation - -`fem-formulation-spec`은 strong/weak form, variables/DOF, kinematics, constitutive update, -residual/tangent, integration, state와 recovery를 implementation-neutral 수학 계약으로 만든다. -선택된 linear/nonlinear/dynamic/eigen/contact/material family의 reference만 읽는다. - -### Numerical review - -`fem-numerical-review`는 formulation을 독립 검토하고 requirement를 falsify할 verification -coverage를 정의한다. Logical quantity, identity, location, units와 tolerance 근거까지 소유하지만 -physical dataset/file layout은 I/O stage에 남긴다. - -### I/O definition - -`fem-io-contract`은 선택된 external syntax와 semantic model, versioned result schema 및 -comparison identity 사이를 mapping한다. 미지원 semantic construct, validation과 diagnostic을 -명시한다. Subset 지원을 full compatibility로 표현하지 않는다. - -### Planning, implementation와 correction - -`fem-implementation-tdd`는 approved upstream bundle을 작은 RED/GREEN step으로 계획하고 C++ -변경, configured build/test와 필요한 reference comparison evidence를 만든다. Implementation은 -upstream contract, tolerance 또는 reference artifact를 결과에 맞춰 고치지 않는다. - -Executor의 process/session 재시도는 transport attempt이며 Coordinator의 normalized -failure/correction budget과 별개다. 동일 `retry_key`의 correction은 한 번만 허용한다. - -### Physics evaluation - -`fem-physics-review`는 numerically passing result가 문서화된 equilibrium, sign, symmetry, -energy, mode와 model coverage 기대를 만족하는지 독립 검토한다. 새 acceptance를 즉석에서 -만들지 않는다. - -### Release readiness - -`fem-release-readiness`는 동일 feature/contract revision의 traceability, gate evidence, -limitations와 release-note draft를 감사한다. Readiness verdict는 publish, tag, deploy 또는 -external release 권한이 아니다. - -## 5. Supporting skill - -| Skill | 적용 조건 | +| Skill | 적용 조건과 경계 | | --- | --- | -| `fem-theory-query` | 사용자가 configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때 | -| `harness` | implementation phase를 만들거나 bounded Executor 작업을 수행할 때 | -| `review` | repository diff를 architecture, numerical, test와 evidence 기준으로 읽기 전용 검토할 때 | +| `fem-theory-query` | configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때. 일반 FEM 질문 전체에 적용하지 않음 | +| `harness` | 구성된 build/test를 명시적으로 실행할 때. `python scripts/execute.py` 사용; phase 계획·agent 호출·Git 관리 기능 없음 | +| `review` | 요청된 diff와 영향받는 계약·correctness·검증·범위를 읽기 전용 검토할 때. 수정 요청 없이 finding을 고치지 않음 | -`fem-theory-query`는 일반 FEM 질문 전체를 가로채지 않는다. Vault path는 environment, -project instruction 또는 untracked local override에서 해석하며 workstation 절대 경로를 -commit하지 않는다. External research나 vault write는 해당 요청과 권한이 있을 때만 수행한다. +`fem-theory-query`의 vault resolution과 citation 규칙을 유지한다. Workstation 절대 경로는 +untracked local override 등에 두고 commit하지 않는다. 외부 조사나 vault 수정에는 해당 +요청과 권한이 필요하다. Harness는 수치·물리·reference 검증이나 외부 solver 권한을 대신하지 +않으며 명령과 설정은 [HARNESS](HARNESS.md)를 따른다. -Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은 -guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다. +## 결과와 evidence -## 6. 공통 evidence +결과에는 작업을 지지하는 판단·가정, 변경 파일, 실제 명령·exit code·결정적 판정값, +evidence 경로와 미해결 항목·제한만 필요한 만큼 기록한다. 수치 비교는 quantity, +identity/component, units, metric과 승인된 tolerance source를 확인한다. -Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다. +실행하지 않았거나 실패한 검사, missing/stale blocking evidence를 통과로 표시하지 않는다. +긴 로그와 이미 정의된 수식을 여러 보고서에 복사하거나 의미 변화 없는 문서 편집마다 +revision/hash·gate 기록을 새로 만들지 않는다. 실제 계약이 변경되면 영향받은 evidence의 +유효성을 다시 확인한다. -- `feature_id`, `stage`, `outcome`, `next_owner` -- `evidence_paths`, current contract revision과 artifact identity/hash -- decisive finding, command, exit code, duration과 test count -- comparison quantity, identity, units, metric와 tolerance source -- `failure_classification`, `retry_key`, `attempt` -- `escalation_class`, actionable blocker와 residual risk +동작 변경은 해당 테스트로 검증하고 버그는 가능한 경우 실패를 재현한다. 변경 중에는 관련 +검사를 실행하며 솔버 기능 완료 시 구성된 전체 build/test와 필수 reference 비교를 한 번 +수행한다. 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되 이후 변경· +실패가 없으면 반복하지 않는다. 충분한 기존 coverage가 있는 refactor에는 형식적인 새 +테스트를 요구하지 않는다. -필요한 명령이 실패했거나 실행되지 않았고 blocking evidence가 stale/missing이면 `pass`를 -반환하지 않는다. Raw log 전체를 모든 skill 문서에 복사하지 않고 재현 가능한 digest와 원본 -artifact path를 남긴다. +## Reference와 사용자 결정 경계 -## 7. Abaqus reference policy +Abaqus의 공개 입력 의미·출력 정의·검증 사례는 승인된 범위의 reference로 사용한다. +비공개 내부 알고리즘·상태·결과 생성 절차의 동등성이나 full compatibility를 주장하지 +않는다. 수치적 exact equality는 내부 동등성의 evidence가 아니다. -Abaqus는 project가 선택한 경우 다음 공개 observable convention의 기준으로 사용한다. +저장된 artifact의 읽기와 외부 Abaqus 실행은 다른 권한이다. Reference 생성·수정·복원은 +명시적으로 승인된 범위에서만 다루며 구현 통과를 위해 값을 보정하지 않는다. Numerical +Review는 공통 TOLERANCE 안에서 기능별 비교량·identity·판정 구분을 정의하며 임의로 +수치 기준을 완화하지 않는다. -- input keyword와 option의 문서화된 syntax/semantics -- model data와 history/step data의 구분 -- element formulation, integration과 output location 정의 -- analysis procedure와 convergence 개념 -- verification guide의 benchmark 구성과 expected physical behavior +지원 physics·공개 호환성·authoritative schema·acceptance 변경, 해결되지 않은 필수 +계약/reference 충돌, 외부 권한이나 파괴적·원격·release 작업은 사용자 결정 경계를 따른다. +이미 승인된 범위의 일반 작업과 skill 인계에 반복 승인을 추가하지 않는다. -Skill은 비공개 내부 구현을 추정하지 않고 full compatibility나 solver equivalence를 주장하지 -않는다. External Abaqus execution은 저장된 artifact를 읽는 것과 다른 권한이며 라이선스, -자격증명, 비용과 명시된 command scope가 확보된 경우에만 수행한다. +## Skill 변경의 확인 -## 8. Autonomous decision boundary - -Skill은 approved contract 안의 내부 naming/layout, test 분해, diagnostic, 문서 형식, 기술 -근거가 유일한 convention과 명백한 결함 수정을 자율적으로 처리한다. Numerical Review는 -`docs/TOLERANCE.md`와 evidence로 feature-specific metric/tolerance를 결정할 수 있다. - -지원 physics/범위, 공개 compatibility, authoritative schema, product acceptance를 바꾸는 -tolerance, 상충하는 필수 reference evidence, 외부 권한 또는 destructive/release 작업만 -사용자 결정이 필요하다. “계속할까요?” 같은 routine approval을 stage 사이에 추가하지 않는다. - -## 9. Validation - -Skill 변경 후 다음을 검증한다. - -- lifecycle skill 8개와 supporting skill의 frontmatter parse -- 폴더명, `name`, `openai.yaml` invocation과 agent 참조 일치 -- relative reference link의 존재와 repository containment -- canonical output path와 common outcome vocabulary -- product-specific legacy name과 machine-specific absolute path 부재 -- realistic requests를 이용한 최소 forward-test - -Project에 validator가 제공되면 해당 validator와 repository pytest suite를 모두 실행한다. -Validator 부재 또는 미실행을 성공으로 간주하지 않는다. +Skill 자체를 변경할 때 영향받는 frontmatter, 폴더명·invocation·agent 참조, 상대 링크와 +조건부 reference를 확인한다. 변경된 동작에 필요한 최소 검사를 선택하며 제공되는 +validator나 관련 repository 검사가 필요하면 실행한다. 문서 설명만 수정하는 작업에 +전체 pytest나 solver build를 강제하지 않는다. 정적 검토와 실제 실행 여부를 구분해 기록한다.