baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify documents

Browse Source
This commit is contained in:
KOKO\Mimi
2026-09-05 15:14:21 +09:00
parent 31dac85192
commit 97e4d7a971
79 changed files with 4570 additions and 2787 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+87 -67
View File
@@ -1,6 +1,7 @@
# Project: FESA Structural Solver
## 기술 스택
- C++17 이상
- MSVC on Windows
- CMake + CTest
@@ -10,23 +11,18 @@
- Abaqus `.inp` keyword subset input
## 프로젝트 정체성
- FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하고 검증하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다.
- FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다.
- 새 기능은 입력 keyword만 인식하거나 element kernel만 존재한다고 완성된 것이 아니다. Semantic model, equation system, 해법, 결과 복구, HDF5 외부 계약과 독립 검증 evidence가 하나의 추적 가능한 기능을 이뤄야 한다.
- 프로젝트의 배경, 목적, 사용자, 범위는 `docs/PRD.md`에서 확인한다.
- 전체 아키텍처와 모듈별 책임은 `docs/ARCHITECTURE.md`에서 확인한다.
- 주요 아키텍처 결정과 그 이유 및 트레이드오프는 `docs/ADR.md`에서 확인한다.
- C++ naming, formatting, Doxygen와 변경 검증 규약은 `docs/CODINGSTYLE.md`를 따른다.
- 외부 reference tolerance 값, 판정 과정, 보고서와 변경 관리는
`docs/TOLERANCE.md`를 따른다.
- AI 에이전트는 설계나 구현 결정을 내리기 전에 PRD에서 제품 범위를, ARCHITECTURE에서 소유권과 데이터 흐름을, ADR에서 이미 결정된 트레이드오프를 먼저 확인한다. 기능별 요구조건, 연구, 정식화, 수치/reference 검토, I/O, 구현, 검증, 물리 및 release 의미는 `docs/<feature-id>/`의 승인 문서를 source of truth로 삼는다.
- Harness는 솔버 자체가 아니라 요구조건, TDD, phase 실행, 검증을 통제하는 개발 운영 인프라이다. 전체 실행 흐름은 `docs/HARNESS_WORKFLOW.md`, 설치와 설정은 `docs/HARNESS.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, 내부 상태 또는 결과 생성 절차의 동등성을
주장하거나 목표로 삼지 않는다. 수치 결과의 exact equality는 허용되지만 내부 동작
동등성의 evidence가 아니다.
- 기능별로 승인된 Abaqus keyword subset만 입력 형식으로 지원한다. Abaqus 결과는 승인된
비교량의 외부 수치 reference일 뿐 FESA 내부 알고리즘 계약이 아니다.
- 공식 solver output은 HDF5 `results.h5`이다.
- 공식 solver output은 입력 경로의 lexical sibling인 HDF5 `<stem>_results.h5`이다. 파일명과 저장 계약은 PRD와 ARCHITECTURE를 따른다.
- reference 결과는 FESA와 같은 Abaqus `.inp` 모델을 Abaqus로 해석해 생성한 CSV 파일이다.
- reference case는 기능 문서가 지정한 기존 `.inp`와 실제 비교에 필요한 Abaqus CSV 경로를
그대로 사용한다. canonical 이름, legacy-alias 승인, bundle `README.md`, `metadata.json`,
@@ -35,20 +31,34 @@
- 비교기는 필요한 source row identity와 component를 결정적으로 대응시키고 누락, 추가,
중복, nonfinite 값을 tolerance 전에 거부한다. Reference artifact는 rename, rewrite 또는
보정하지 않는다.
- 모든 외부 reference comparison은 `docs/TOLERANCE.md`의 공통 정책을 사용한다.
설계 근거는 `docs/superpowers/specs/2026-08-17-common-reference-tolerance-design.md`와
ADR-022에 보존한다. 동일 logical quantity, unit dimension, coordinate system과 blocking behavior의
component family에서 Abaqus-only scale `S=max(abs(reference))`를 구한다. `abs(reference)`가
`0.01*S` 이하인 행은 `abs(fesa-reference) <= 0.01*S`, 그 외 행은 상대오차 `<=0.05`로
판정하고, family scale-relative RMS `RMS(error)/S <= 0.01`도 함께 통과해야 한다. 별도
absolute-error gate는 사용하지 않으며 zero-scale family는 FESA도 exact zero일 때만
통과한다.
- 모든 외부 reference comparison의 scale, near-zero/relative/RMS 판정, zero-scale 처리와 보고서는 [TOLERANCE](docs/TOLERANCE.md)의 승인된 공통 정책을 따른다. Numerical Review는 이 정책 안에서 기능별 비교량, identity/component와 blocking/diagnostic 구분을 정의하며 고정된 수치 기준을 임의로 선택·완화하지 않는다. 정책 변경은 해당 문서의 사용자 승인과 ADR 절차를 따른다.
- B33 section-resultant reference는 `(instance, element label, endpoint node label,
component)`로 HDF5 element endpoint와 직접 대응한다. Node-station collapse 또는 평균을
사용하지 않는다. MITC4 `U1/U2/U3`는 blocking, `UR1/UR2/UR3`는 warning-only 분류를
유지하면서 같은 공통 수치 정책을 사용한다.
- CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다.
## 문서 기준과 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/<feature-id>/`에 둔다. Coordinator가 안정적인 kebab-case Feature ID를 정하고 모든 dispatch에서 같은 폴더와 revision을 사용한다. 기존 `docs/features/<feature-id>/` 자료가 있으면 자동 이동·복제하지 않고 필요한 경로와 revision을 참조한다.
- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크나 결정을 루트 문서에 누적하지 않는다. 프로젝트 공통 지침 수정은 별도 사용자 요청으로 승인된 범위에서만 수행한다.
- Coordinator는 새 Feature에 아래 관리 문서를 실제 요구사항으로 초기화한다. 재개 시 기존 기록을 읽고 필요한 부분만 갱신하며, 승인되지 않은 내용을 승인으로 표시하거나 후속 stage의 빈 보고서를 미리 만들지 않는다.
| 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 상태 원본 |
- 관리 문서에서 실제 프로젝트 기준 문서를 상대 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는 각각의 지정 경로에 유지하고 보고서에서 참조한다. 필수 검증을 생략했다면 미실행 사실과 이유를 남긴다.
## FESA 개발의 핵심 원칙
### 물리와 수치 계약
@@ -70,7 +80,7 @@
- Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
- AnalysisModel은 현재 step에서 활성화된 elements, loads, boundary conditions, properties/materials의 non-owning view를 제공하며 Domain을 복사하지 않는다. 따라서 Domain은 AnalysisModel보다 오래 살아야 한다.
- DofManager는 node별 자유도 정의, constrained/free mapping, equation numbering, sparse pattern ownership을 전담한다. Node 또는 Element 내부에 equation id를 분산 저장하지 않는다.
- AnalysisState는 해당 procedure가 실제로 사용하는 mutable solution과 recovery row만 소유한다. V0는 full displacement/external/internal force/residual/reaction과 step/frame 및 beam recovery rows만 보관하며 미래 state를 미리 할당하지 않는다.
- AnalysisState는 해당 procedure가 실제로 사용하는 mutable solution과 recovery row만 소유한다. 구체적인 state는 승인된 procedure 계약과 ARCHITECTURE를 따르며 미래 state를 미리 할당하지 않는다.
- MKL, TBB, HDF5, Win32 API와 vendor type은 public solver core에 노출하지 않는다. `LinearSolver`, `ParallelFor`, `ResultsWriter`, `Vector`, `Matrix`, `SparseMatrix` 경계 뒤에 둔다.
- 해석 단계는 실패할 수 있는 candidate를 완성하고 검증한 뒤 소유 state/output에 반영한다. 실패 시 기존 state와 기존 최종 HDF5를 가능한 계약 범위에서 보존한다.
@@ -85,14 +95,16 @@
### 개발 운영 인프라
- Codex custom agent의 `model_reasoning_effort` 기본값은 `extra high`로 둔다.
- Harness runner는 `scripts/execute.py`에 둔다.
- `scripts/execute.py`는 `feat-<phase-name>` branch prefix를 사용한다.
- runner는 `git add -A`로 변경사항을 stage하므로 실행 전 clean worktree 또는 별도 Git worktree를 사용한다.
- Hook 연결은 `.codex/hooks.json`, 구현은 `scripts/hooks/`와 `scripts/msvc_harness/`에 둔다.
- PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하는 guardrail이며 RED 실행을 증명하지 않는다.
- Stop은 `.harness/config.json` 또는 자동 감지 결과에 따라 MSVC build와 test를 모두 검증한다.
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.
- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
- Harness runner는 [scripts/execute.py](scripts/execute.py)이며 `feat-<phase-name>` 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를 변경하지 않는다.
- Executor의 process/session transport 시도는 최대 2회이며 Coordinator의 correction budget과 별개다. 구현·상위 계약·환경·물리 실패를 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 상태로 유지한다.
## 기능을 추가할 때의 판단 기준
@@ -104,71 +116,79 @@
- Element API에 kernel이 존재하는 것과 Abaqus keyword/CLI에서 그 기능을 노출하는 것은 별도 계약이다. 예를 들어 V0의 line-load kernel은 `*DLOAD` 지원을 뜻하지 않는다.
## 개발 프로세스
- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다.
- CRITICAL: 빌드 경고를 새로 추가하지 말 것.
- 기능 개발은 아래 `Agent/Skill Workflow` 표의 8단계 gate를 순서대로 통과해야 한다.
- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다. 문서 수정·읽기 전용 검토를 새 solver feature 전체 workflow로 확대하지 않는다.
- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, outcome, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID의 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
## Agent/Skill Workflow
`coordinator-agent`는 유일한 main agent로서 `docs/<feature-id>/coordination.md`의 8단계
worklist, sub-agent dispatch, evidence gate와 workflow closure를 관리한다. 나머지 모든
profile은 Coordinator가 한정된 단계 작업으로 호출하는 sub-agent이며, peer agent를 직접
호출하거나 다음 gate로 진행하지 않는다. 유한요소 구조해석 지식이 필요할 때는
`.codex/skills/fem-theory-query`를 보조 skill로 사용할 수 있다.
| 단계 | 담당 sub-agent | 필수 skill | `docs/<feature-id>/` 산출물 |
Solver feature workflow에서 `coordinator-agent`만 main agent로서 상태 전이와 closure를
소유하며 다음 eligible specialist에게 한 번에 하나의 bounded task를 dispatch한다.
Specialist는 peer를 호출하거나 다음 gate로 진행하거나 자신의 산출물을 최종 승인하지 않는다.
Intake/coordination은 아래 정규 stage와 별도로 관리한다.
| 단계 | 담당 sub-agent | 필수 skill | 기본 보고서 (`docs/<feature-id>/`) |
| --- | --- | --- | --- |
| 1. 요구조건 | `requirement-agent` | `fesa-requirements-baseline` | `requirements.md` |
| 2. 연구 | `research-agent` | `fesa-research-evidence`, 필요 시 `fem-theory-query` | `research.md` |
| 3. 정식화 | `formulation-agent` | `fesa-formulation-spec` | `formulation.md` |
| 4. 수치 검토 + reference model 계약 | `numerical-review-agent` | `fesa-numerical-review` | `numerical-review.md`, `reference-model.md` |
| 5. I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `io.md` |
| 6. 구현 계획 + C++ 구현 + build/test + reference comparison | `implementation-planning-agent`, `implementation-agent` | `fesa-cpp-msvc-tdd`, 계획 시 project-local `harness` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
| 7. 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `physics-evaluation.md` |
| 8. 배포 준비 | `release-agent` | `fesa-release-readiness` | `release.md` |
| 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` |
`correction-agent`는 정규 단계가 아니라 반복되거나 원인이 불명확한 구현 실패를 다루는
on-demand rework sub-agent다. Coordinator가 호출할 때만 `docs/<feature-id>/corrections.md`에
원인, 수정과 재검증 결과를 기록하고 Implementation 단계로 반환한다.
Implementation Planning Agent는 구현 계획 요청에서 `.agents/skills/harness`를 반드시
사용한다. 먼저 여러 자기완결적 Step의 초안을 제시하고 사용자 승인을 받은 뒤에만
`phases/index.json`, `phases/<task-name>/index.json`, `phases/<task-name>/stepN.md`를
생성한다. Harness 실행은 별도 사용자 요청이 있을 때만 수행한다.
- 위 8개 lifecycle skill은 [.codex/skills](.codex/skills)에 있다. Planning은 할당된 `phases/index.json`, `phases/<phase>/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 진행을 관리하며 실패 증거를 지우고 즉시 재실행하지 않는다.
## 최소 검증 진입점
세부 target graph, dependency normalization과 Windows runtime staging은 `docs/ARCHITECTURE.md`와 실제 CMake 파일을 따른다. `.harness/config.json`이 존재하면 그 설정을 우선한다.
아래 명령은 해당 구현·검증 작업에만 사용한다. 문서만 수정하는 작업의 정적 검토를 위해
build/test를 실행하지 않는다. 실행할 명령은 승인된 step/plan에서 확인하고,
`.harness/config.json`, preset·project metadata와 프로젝트 지침에 대조한 뒤에만 기본값을
사용한다. Target graph, dependency normalization과 Windows runtime staging은
ARCHITECTURE와 실제 CMake 파일을 따른다.
### Harness Python 검증
```powershell
uv run --with pytest python -m pytest -v -rs
uv run --with pytest python -B -m pytest -v -rs
```
### Phase 실행
```powershell
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push
```
`<phase-dir>`는 할당된 phase로 대체한다. `--push`는 원격 push가 명시적으로 승인된 경우에만 추가한다.
### CMake/CTest 프로젝트
```powershell
$gtestSource = "C:/path/to/googletest"
$mklDir = "C:/path/to/oneAPI/mkl/lib/cmake/mkl"
$tbbDir = "C:/path/to/oneAPI/tbb/lib/cmake/tbb"
$hdf5Dir = "C:/path/to/HDF5/cmake"
현재 [CMakePresets.json](CMakePresets.json)의 MSVC x64 Debug preset 사용 예시다.
MSVC x64 developer 환경에서 `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, `HDF5_DIR`
환경변수를 설치된 dependency 경로로 설정한다. `FESA_GTEST_SOURCE_DIR`는 승인된 local
GoogleTest source checkout, 나머지는 각 package의 CMake config directory를 가리킨다.
cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
"-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
"-DMKL_DIR=$mklDir" `
"-DTBB_DIR=$tbbDir" `
"-DHDF5_DIR=$hdf5Dir"
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
```powershell
cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug --show-only=json-v1
ctest --preset windows-msvc-ninja-debug --output-on-failure
```
`FESA_GTEST_SOURCE_DIR`는 approved local GoogleTest source checkout을 반드시 가리켜야 한다. MKL/TBB/HDF5가 기본 package search에서 발견되지 않는 환경에서는 나머지 세 config directory도 명시한다. FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 기준으로 한다.
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를 기준으로 한다.