modify harness framework

docs/ADR.md

@@ -6,18 +6,18 @@ FESA의 architecture decision은 solver correctness, verification traceability,
 ---
 
 ### ADR-001: FESA는 구조해석 솔버 프로젝트이고 Harness는 운영 인프라로 둔다
-**결정**: 저장소의 주 목적은 유한요소법 기반 구조해석 솔버 개발이다. Harness scaffold는 phase execution, TDD guard, commit validation, workspace validation을 제공하는 보조 계층으로 유지한다.
+**결정**: 저장소의 주 목적은 유한요소법 기반 구조해석 솔버 개발이다. Harness는 승인된 Step 계획, 독립 세션 실행, PreToolUse guardrail, Stop MSVC build/test 검증을 제공하는 보조 계층으로 유지한다.
 
 **이유**: 기존 문서가 Harness 중심이면 agent가 solver architecture, FEM verification, Abaqus/HDF5 계약보다 운영 스크립트에 과도하게 맞춰 행동한다.
 
-**트레이드오프**: Harness 문서의 비중은 낮아지지만, 검증 명령과 hook 정책은 계속 필수 운영 규칙으로 유지한다.
+**트레이드오프**: Harness 문서의 비중은 낮아지지만, `docs/HARNESS_WORKFLOW.md`의 실행 계약과 `.codex/hooks.json`의 검증 정책은 계속 필수 운영 규칙으로 유지한다.
 
 ### ADR-002: C++17/MSVC/CMake/CTest를 기본 구현 환경으로 둔다
 **결정**: 기본 solver 구현과 validation은 C++17 이상, Visual Studio 17 2022 generator, x64 platform, Debug config, CMake, CTest로 수행한다.
 
 **이유**: FESA의 목표 환경은 Windows/MSVC 기반 C++이다. CMake/CTest는 solver source tree가 추가되거나 확장될 때 가장 일관된 build/test entry point다.
 
-**트레이드오프**: Visual Studio solution-only workflow는 기본 지원하지 않는다. 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
+**트레이드오프**: FESA solver source는 CMake/CTest를 기본으로 유지한다. Harness 자체는 `.harness/config.json`에 solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할 수 있지만, 이는 FESA 제품이 solution-only workflow를 지원한다는 의미가 아니다.
 
 ### ADR-003: Abaqus `.inp` full compatibility가 아니라 기능별 keyword subset을 지원한다
 **결정**: FESA parser는 Abaqus keyword/data/comment line 규칙을 따르되, 기능별로 승인된 keyword subset만 지원한다. 미지원 keyword는 명확한 diagnostic을 남긴다.
@@ -75,9 +75,16 @@ FESA의 architecture decision은 solver correctness, verification traceability,
 
 **트레이드오프**: reference 준비가 느려질 수 있다. 대신 검증 기준의 신뢰도와 감사 가능성이 높아진다.
 
-### ADR-011: C++ production 변경은 TDD guard와 workspace validation을 통과해야 한다
-**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다. 기본 검증은 `python -m unittest discover -s scripts -p "test_*.py"`와 `python scripts/validate_workspace.py`를 사용한다.
+### ADR-011: 구형 단일 검증 진입점 계약을 폐기한다
 
-**이유**: FEM solver 결함은 작은 부호, DOF ordering, integration rule 오류에서도 발생한다. 테스트 없는 변경을 막아야 reference validation 이전 단계에서 회귀를 줄일 수 있다.
+**상태**: ADR-012로 대체됨.
 
-**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
+**결정**: 삭제된 legacy validation entry point, legacy Python test discovery, 환경 변수 기반 command override를 Harness의 기본 검증 계약으로 사용하지 않는다.
+
+### ADR-012: Harness는 계획, 실행, Hook 검증의 세 계층으로 운영한다
+
+**결정**: 계획은 `.agents/skills/harness`, Step 실행과 Git 상태 관리는 `scripts/execute.py`, 도구 호출 전 정책과 종료 전 검증은 `.codex/hooks.json`에 연결된 `scripts/hooks/`가 담당한다. C++ production 변경은 관련 테스트 파일이 있어야 하며, 실제 RED 실패와 GREEN 성공은 같은 Step 안에서 확인한다. Stop은 `.harness/config.json` 또는 자동 감지 결과로 전체 MSVC build/test를 검증한다. Harness Python 변경은 `uv run --with pytest python -m pytest -v -rs`로 검증한다.
+
+**이유**: 테스트 파일 존재 검사, TDD 실행 증거, 전체 build/test는 서로 다른 책임이다. 이를 분리하면 Hook이 보장하는 범위를 과장하지 않으면서 Step 종료 시 green 상태를 강제할 수 있다.
+
+**트레이드오프**: PreToolUse만으로 구현 전 RED 실행을 증명할 수 없으므로 Implementation report에 RED/GREEN 명령과 결과를 기록해야 한다. C/C++가 없는 저장소는 Stop이 통과하므로 Harness Python 검증은 별도 acceptance command로 유지한다.

docs/ARCHITECTURE.md

@@ -9,7 +9,7 @@ FESA의 아키텍처 목표는 Abaqus `.inp` subset을 내부 semantic model로
 - sparse linear algebra backend isolation
 - deterministic verification
 - incremental feature addition
-- Harness 기반 TDD와 workspace validation
+- Harness 기반 TDD
 
 ## 디렉토리 구조
 ```text
@@ -31,6 +31,9 @@ src/
     analysis/             # static, modal, dynamic, nonlinear procedure drivers
     results/              # recovery, field/history output, diagnostics
     validation/           # comparison metrics and tolerance helpers
+    math/
+      Vector/             # managing double array including vector operation, vector operation must use BLAS from MKL
+      Matrix/             # managing double array including matrix operation, matrix operation must use BLAS from MKL
 tests/
   unit/
   integration/
@@ -43,24 +46,29 @@ reference/
     <model-id>_reactions.csv
     <model-id>_internalforces.csv
     <model-id>_stresses.csv
+.agents/
+  skills/                 # Harness and review skills
 .codex/
-  hooks/                  # Codex hook scripts
-  skills/                 # FESA solver and Harness instructions
+  hooks.json              # PreToolUse/Stop hook registration
+  agents/                 # FESA workflow custom agents
+  skills/                 # FESA solver workflow skills
 docs/                     # Product, architecture, ADR, workflow artifacts
 scripts/
   execute.py              # Phase step executor
-  validate_workspace.py   # Default validation entry point
-  test_*.py               # Harness self-tests
+  hooks/                   # PreToolUse/Stop hook implementations
+  msvc_harness/            # MSVC project discovery and validation adapters
 phases/                   # Optional generated phase plans
 ```
 
 ## Harness Execution Layer
-`scripts/execute.py`:
-- creates or checks out `codex/<phase-name>`
-- refuses to run on a dirty worktree
-- requires per-step `allowed_paths`
-- stages only explicit allowed paths and runner housekeeping files
-- runs Python Harness self-tests and workspace validation before every runner-created commit
+
+Harness는 solver core와 분리된 세 계층의 개발 운영 인프라다.
+
+- 계획 계층: `.agents/skills/harness`가 사용자 승인 전 Step 초안을 만들고, 승인 후 `phases/` 파일을 생성한다.
+- 실행 계층: `scripts/execute.py`가 `feat-<phase-name>` 브랜치에서 Step마다 독립 Codex 세션을 실행하고 상태와 커밋을 관리한다.
+- 검증 계층: `.codex/hooks.json`이 `scripts/hooks/pre_tool_use.py`와 `scripts/hooks/stop_validation.py`를 연결한다. Stop 검증은 `scripts/msvc_harness/`를 통해 MSVC build와 test를 실행한다.
+
+Runner는 `git add -A`를 사용하므로 clean worktree 또는 별도 Git worktree가 실행 전제다. 전체 동작 계약은 `docs/HARNESS_WORKFLOW.md`, 설치와 `.harness/config.json` 설정은 `docs/HARNESS.md`를 source of truth로 삼는다.
 
 ## 모듈 경계
 - `core`는 외부 라이브러리에 의존하지 않는다.
@@ -148,6 +156,9 @@ Results
 ├── ResultFrame
 ├── FieldOutput
 └── HistoryOutput
+
+Vector
+Matrix
 ```
 
 ## 상태 관리
@@ -231,41 +242,3 @@ Schema requirements:
 - Abaqus reference results는 `reference/<model-id>/` 아래 CSV 파일이다.
 - Verification은 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 FESA HDF5 rows와 Abaqus reference CSV rows를 비교한다.
 - FESA HDF5에서 추출한 deterministic CSV view는 optional debugging/review artifact이며 공식 solver output 또는 reference artifact가 아니다.
-
-## Test Architecture
-- unit: parser, DOF map, shape functions, material law, sparse assembly, HDF5 schema
-- integration: small `.inp` to HDF5 end-to-end
-- reference: FESA `results.h5` rows and Abaqus reference CSV rows comparison
-- physics: equilibrium, sign, symmetry, rigid body mode, stress sanity
-- harness: hooks, phase executor, workspace validation
-
-## Hook 흐름
-```text
-apply_patch/Edit/Write
--> .codex/hooks/tdd-guard.py
--> C++ production changes require related tests
-
-git commit command
--> .codex/hooks/pre_commit_checks.py
--> Python Harness self-tests
--> scripts/validate_workspace.py
-```
-
-## Validation 흐름
-```text
-HARNESS_VALIDATION_COMMANDS set
--> run exact commands
-
-CMakePresets.json has msvc-debug configure preset
--> cmake --preset msvc-debug
--> cmake --build preset binary dir --config Debug
--> ctest --test-dir preset binary dir -C Debug
-
-CMakeLists.txt exists
--> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
--> cmake --build build/msvc-debug --config Debug
--> ctest --test-dir build/msvc-debug --output-on-failure -C Debug
-
-No CMake project
--> print guidance and exit successfully
-```

docs/HARNESS.md

@@ -0,0 +1,124 @@
+# Harness 운영 가이드
+
+## Requirements
+
+Windows, Python 3.10 이상, Codex CLI가 필요하다. CMake 프로젝트에는 Visual Studio의
+Desktop development with C++ 워크로드와 MSBuild, CMake/CTest를 설치한다.
+
+## 프로젝트 자동 감지
+
+프로젝트 형식은 다음 순서로 결정한다: `.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
+```
+
+계획을 승인해 phase 파일을 만든 뒤 Executor를 실행한다.
+
+```powershell
+python scripts/execute.py <phase-name>
+python scripts/execute.py <phase-name> --push
+```
+
+## Harness Python 검증
+
+이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
+다음 명령으로 실행한다.
+
+```powershell
+uv run --with pytest python -m pytest -v -rs
+```
+
+## CMake preset 설정
+
+`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
+`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
+지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
+
+```json
+{
+  "version": 1,
+  "projectType": "cmake",
+  "cmake": {
+    "sourceDir": ".",
+    "binaryDir": "out/build/windows-debug",
+    "configurePreset": "windows-debug",
+    "buildPreset": "windows-debug",
+    "testPreset": "windows-debug"
+  }
+}
+```
+
+```powershell
+cmake --preset windows-debug
+cmake --build --preset windows-debug
+ctest --preset windows-debug --output-on-failure
+```
+
+Preset을 쓰지 않는 경우에는 같은 격리된 build directory를 명시한다.
+
+```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
+```
+
+## 직접 MSBuild 설정
+
+`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
+지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
+파일과 인수를 JSON 배열로 적는다.
+
+```json
+{
+  "version": 1,
+  "projectType": "msbuild",
+  "msbuild": {
+    "solution": "MyProject.sln",
+    "configuration": "Debug",
+    "platform": "x64",
+    "testCommand": ["build/tests/Debug/MyProjectTests.exe"]
+  }
+}
+```
+
+```powershell
+MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
+.\build\tests\Debug\MyProjectTests.exe
+```
+
+## 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/**"]
+  }
+}
+```
+
+## 실패 복구
+
+- 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을 확인하고 해당 명령을 단독으로 다시 실행한다. Harness는
+  별도의 로그 파일을 만들지 않는다.

docs/HARNESS_WORKFLOW.md

@@ -0,0 +1,607 @@
+# Harness Framework 동작 과정
+
+이 문서는 자연어 요구사항을 받은 뒤 Harness Framework가 계획을 만들고, 독립된
+Codex 세션에서 Step을 실행하고, MSVC로 C++ 프로젝트를 검증하는 전체 과정을
+설명한다. 설치 및 설정 예시는 [Harness 운영 가이드](HARNESS.md)를 참고한다.
+
+## 1. 핵심 구조
+
+Harness Framework는 다음 세 계층으로 구성된다.
+
+1. **계획 계층**: 요구사항을 분석하고 사용자가 승인할 실행 가능한 Step으로 변환한다.
+2. **실행 계층**: Step Executor가 Step마다 독립 Codex 세션을 실행하고 상태와 Git
+   커밋을 관리한다.
+3. **검증 계층**: PreToolUse 훅이 편집 전 정책을 검사하고, Stop 훅이 종료 전 MSVC
+   빌드와 테스트를 실행한다.
+
+전체 흐름은 다음과 같다.
+
+```text
+사용자 요구사항
+    ↓
+프로젝트 탐색 및 요구사항 논의
+    ↓
+Step 초안 작성
+    ↓
+사용자 승인
+    ↓
+phases/index.json, task index, stepN.md 생성
+    ↓
+Step Executor 시작
+    ↓
+각 Step을 독립 Codex 세션에서 실행
+    ├─ 도구 호출 전: PreToolUse 정책 검사
+    └─ 응답 종료 전: Stop MSVC 빌드·테스트
+    ↓
+성공: 커밋 후 다음 Step
+실패: 수정 또는 최대 3회 재시도
+차단: 사용자 개입을 기다리며 중단
+```
+
+자연어 요구사항만으로 Executor가 자동 시작되지는 않는다. 계획을 사용자가 승인하고
+phase 파일을 생성한 다음 `scripts/execute.py`를 실행해야 구현 루프가 시작된다.
+
+## 2. 요구사항 탐색과 구체화
+
+예를 들어 사용자가 다음 요구사항을 전달했다고 가정한다.
+
+> CMake 기반 C++20 라이브러리에 `divide()` 함수를 추가하고, 0으로 나누면 예외를
+> 발생시키며 GoogleTest 테스트를 작성한다.
+
+계획을 작성하기 전에 다음 자료를 확인한다.
+
+- `AGENTS.md`
+- `docs/PRD.md`
+- `docs/ARCHITECTURE.md`
+- `docs/ADR.md`
+- 관련 제품 코드와 테스트
+- `.harness/config.json`
+
+이 탐색을 통해 다음 조건을 구체화한다.
+
+- 사용하는 MSVC toolset과 C++ 표준
+- CMake 프로젝트인지 Visual Studio solution/project인지
+- 테스트 프레임워크와 테스트 실행 방법
+- public header와 implementation의 의존성 방향
+- 수정할 모듈과 범위 밖 항목
+- 실행 가능한 Acceptance Criteria 명령
+
+요구사항에 결정되지 않은 부분이 있으면 구현 전에 사용자와 논의한다. 위 예에서는
+예외 타입, 정수 또는 부동소수점 연산 여부, public API와 ABI 변경 허용 여부가 이에
+해당한다.
+
+## 3. 요구사항을 Step으로 분해
+
+사용자가 구현 계획 작성을 요청하면 요구사항을 작은 Step으로 나눈다. Step 설계
+규칙은 [Harness Workflow](../.agents/skills/harness/SKILL.md)에 정의되어 있다.
+
+각 Step은 다음 조건을 만족해야 한다.
+
+- 하나의 모듈 또는 명확한 한 가지 책임만 다룬다.
+- 다른 대화 내용을 참조하지 않아도 실행할 수 있도록 자기완결적으로 작성한다.
+- 먼저 읽을 문서와 이전 Step의 관련 파일을 명시한다.
+- 클래스와 함수 시그니처 수준으로 작업 범위를 설명한다.
+- 실제 실행 가능한 빌드·테스트 명령을 Acceptance Criteria로 사용한다.
+- 성공, 오류, 사용자 개입 필요 상태의 판정 기준을 적는다.
+- 범위 밖 기능과 기존 테스트 회귀를 명시적으로 금지한다.
+
+예시 Step은 다음과 같은 내용을 포함할 수 있다.
+
+```text
+Step 0: division-api
+
+읽어야 할 파일
+- AGENTS.md
+- include/calculator.hpp
+- src/calculator.cpp
+- tests/calculator_test.cpp
+
+작업
+- divide(double lhs, double rhs)의 실패 테스트를 먼저 추가한다.
+- rhs가 0이면 std::invalid_argument가 발생하도록 최소 구현한다.
+
+Acceptance Criteria
+- CMake/MSBuild 빌드가 성공한다.
+- 전체 테스트가 성공한다.
+- 새로운 컴파일러 경고가 없다.
+```
+
+### TDD와 Step 경계
+
+프로젝트 규칙은 실패하는 테스트를 먼저 요구하지만 Stop 훅은 Codex가 Step을 종료할
+때 전체 테스트 성공을 요구한다. 따라서 다음처럼 실패 상태를 Step 사이에 남겨둘 수
+없다.
+
+```text
+Step 0: 실패하는 테스트만 추가하고 종료
+Step 1: 제품 코드를 구현해 테스트 통과
+```
+
+실제 red-green 순서는 하나의 Codex 실행 안에서 완료되어야 한다.
+
+```text
+테스트 작성
+→ 테스트 실패 확인
+→ 최소 제품 코드 구현
+→ 테스트 성공 확인
+→ Step 종료
+```
+
+즉, 테스트가 구현보다 먼저 작성되는 순서는 지키되 각 Step은 최종적으로 green
+상태여야 한다.
+
+## 4. 사용자 승인 후 생성되는 파일
+
+Step 초안을 사용자가 승인한 뒤에만 다음 파일을 생성한다.
+
+```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"
+    }
+  ]
+}
+```
+
+상태별 기록은 다음과 같이 나뉜다.
+
+| 상태 | Codex가 기록 | Executor가 기록 |
+|---|---|---|
+| `completed` | `summary` | `completed_at` |
+| `error` | `error_message` | `failed_at` |
+| `blocked` | `blocked_reason` | `blocked_at` |
+
+Executor는 task의 `created_at`과 Step의 `started_at`도 기록한다. `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 디렉터리와 task index가 존재하는지 검사한다.
+2. 이전 실행에서 `error` 또는 `blocked`로 끝난 Step이 있는지 검사한다.
+3. `feat-{phase-name}` 브랜치를 생성하거나 checkout한다.
+4. `AGENTS.md`와 `docs/*.md`를 guardrail로 읽는다.
+5. task의 `created_at`이 없으면 기록한다.
+6. 첫 번째 `pending` Step부터 순차 실행한다.
+
+`AGENTS.md`와 모든 `docs/*.md` 내용은 각 Codex 프롬프트에 직접 삽입된다. 따라서
+이 문서들은 참고 자료가 아니라 실제 실행 입력이다. 서로 충돌하거나 placeholder가
+남아 있으면 Codex도 그 모순을 입력으로 받는다.
+
+## 6. Step마다 독립 Codex 세션 실행
+
+Executor는 각 Step을 다음 형태의 독립 프로세스로 실행한다.
+
+```text
+codex exec
+  --json
+  --sandbox workspace-write
+  --dangerously-bypass-hook-trust
+  --cd <repository-root>
+  -
+```
+
+Codex에 전달하는 프롬프트는 다음 내용의 조합이다.
+
+```text
+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이다.
+
+## 8. Codex 종료 전 Stop 검증
+
+Codex가 Step 작업을 끝내고 응답을 종료하려 하면
+[Stop 훅](../scripts/hooks/stop_validation.py)이 실행된다. Stop 훅은 변경 파일만이
+아니라 발견된 C/C++ 프로젝트 전체를 빌드하고 테스트한다.
+
+### 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 <source> -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 <configurePreset>
+cmake --build --preset <buildPreset>
+ctest --preset <testPreset> --show-only=json-v1
+ctest --preset <testPreset> --output-on-failure
+```
+
+이 경우 모든 명령은 `cmake.sourceDir`에서 실행하고 compiler metadata 검사는 설정한
+`binaryDir`에서 수행한다.
+
+### 9.3 직접 MSBuild
+
+[MSBuild adapter](../scripts/msvc_harness/adapters/msbuild.py)는 다음 순서로 실행한다.
+
+```powershell
+MSBuild.exe <solution-or-vcxproj> /m /nologo `
+  /p:Configuration=<configuration> `
+  /p:Platform=<platform>
+
+<msbuild.testCommand>
+```
+
+직접 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 훅은 출력 없이 종료한다. Codex가 정상 종료하면
+Executor가 task index를 다시 읽는다.
+
+Codex가 Step을 다음처럼 기록한 경우:
+
+```json
+{
+  "step": 0,
+  "name": "division-api",
+  "status": "completed",
+  "summary": "divide API와 0 나누기 테스트를 추가함"
+}
+```
+
+Executor는 `completed_at`을 기록하고 변경사항을 커밋한 뒤 다음 `pending` Step을
+실행한다.
+
+### 11.2 Stop 검증 실패
+
+Stop 훅은 Codex hook protocol에 따라 다음 형태의 응답을 출력한다.
+
+```json
+{
+  "continue": false,
+  "stopReason": "build failed ...",
+  "systemMessage": "build failed ..."
+}
+```
+
+Codex 프로세스에 대한 훅 자체의 종료 코드는 0이지만 `continue: false`가 Codex의
+응답 종료를 막는다. Codex는 같은 세션에서 오류를 확인하고 수정을 계속한다.
+
+### 11.3 Executor 재시도
+
+Codex 프로세스가 끝났는데 Step 상태가 `completed` 또는 `blocked`가 아니면 Executor가
+새 Codex 세션으로 재시도한다.
+
+```text
+첫 번째 시도 실패
+→ 오류를 다음 프롬프트에 삽입
+→ 두 번째 독립 Codex 실행
+→ 다시 실패하면 세 번째 독립 Codex 실행
+→ 세 번째도 실패하면 error 기록 후 종료
+```
+
+즉, 실패 복구에는 두 층이 있다.
+
+1. Stop 훅이 같은 Codex 세션에서 수정하도록 요구한다.
+2. 세션 자체가 성공하지 못하면 Executor가 새 세션으로 최대 3회 재시도한다.
+
+### 11.4 사용자 개입 필요
+
+인증, API 키, 수동 설치처럼 Codex가 자동으로 해결할 수 없는 문제가 있으면 Step을
+`blocked`로 기록한다. Executor는 `blocked_at`과 top-level 상태를 갱신하고 종료 코드
+2로 중단한다.
+
+재개하려면 원인을 해결하고 해당 Step을 `pending`으로 되돌린 뒤
+`blocked_reason`을 제거하고 다시 실행한다. `error`도 같은 방식으로 `pending`으로
+되돌리고 `error_message`를 제거한 뒤 재실행한다.
+
+## 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
+
+커밋 과정은 `git add -A`를 사용한다. 실행 전에 작업 트리에 관련 없는 사용자
+변경사항이 남아 있으면 그 변경도 Step 커밋에 포함될 수 있다. 따라서 깨끗한
+worktree 또는 별도 Git worktree에서 실행하는 것이 안전하다.
+
+## 13. 요구사항 종류별 동작
+
+| 받은 요구사항 또는 변경 | PreToolUse 동작 | Stop 동작 |
+|---|---|---|
+| 새 C++ 제품 파일 추가 | 대응 테스트가 먼저 없으면 차단 | 전체 빌드·테스트 |
+| 기존 C++ 구현 또는 header 수정 | 대응 테스트 파일 존재 여부 검사 | 전체 빌드·테스트 |
+| 테스트 파일 추가 | TDD 차단 없이 허용 | 모든 테스트가 성공해야 종료 |
+| `main.cpp` 수정 | TDD 대응 테스트 검사 면제 | 전체 빌드·테스트 |
+| 문서, JSON, Python 수정 | C++ TDD 검사 없음 | C++ 프로젝트가 있으면 전체 검증 |
+| 위험한 Git 또는 삭제 명령 | 즉시 차단 | 도달하지 않음 |
+| C++ 파일은 있지만 build metadata 없음 | 편집은 허용될 수 있음 | orphan 프로젝트 오류 |
+| 직접 MSBuild인데 `testCommand` 없음 | 편집은 허용될 수 있음 | 설정 오류로 종료 차단 |
+| C/C++가 전혀 없는 저장소 | 관련 편집 검사 없음 | 검증할 프로젝트가 없어 통과 |
+
+## 14. 적용 전 준비사항
+
+이 저장소는 대상 C++ 프로젝트에 맞게 채워 사용하는 템플릿이다. 실행 전 다음을
+확인한다.
+
+1. `AGENTS.md`의 프로젝트명, toolset, C++ 표준, 테스트 프레임워크, CRITICAL 규칙을
+   실제 값으로 교체한다.
+2. `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`의 placeholder와 예시를 실제
+   프로젝트 정보로 교체한다.
+3. 기본 자동 감지로 충분하지 않을 때만 `.harness/config.example.json`을 참고해
+   `.harness/config.json`을 만든다.
+4. CMake 또는 MSBuild metadata와 테스트 실행 방법을 확인한다.
+5. `phases/`가 없다면 요구사항 논의와 계획 승인을 거쳐 task 파일을 먼저 만든다.
+6. Executor 실행 전에 Git working tree가 깨끗한지 확인한다.
+
+특히 `AGENTS.md`와 `docs/*.md`는 각 Codex 실행에 그대로 주입된다. C++ 프로젝트에서
+TypeScript 예시나 미완성 placeholder가 남아 있으면 실제 작업 지시와 충돌할 수 있다.

docs/PRD.md

@@ -20,11 +20,11 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
 6. `LinearSolver` adapter를 통한 MKL PARDISO backend와 향후 iterative solver 확장
 7. HDF5 기반 `ResultStep` -> `ResultFrame` -> `FieldOutput`/`HistoryOutput` 저장
 8. FESA HDF5 rows와 `reference/<model-id>/` 아래 Abaqus reference CSV rows의 직접 비교
-9. CMake/MSVC/x64/Debug, CTest, Harness validation, TDD guard 기반 개발 검증
+9. CMake/MSVC/x64/Debug, CTest 기반 개발 검증
 
 ## V0 범위
-- 선형 정적 해석 골격
-- 첫 end-to-end 기능 후보: 1D truss/bar element
+- 선형 정적 해석 파이프라인 구현
+- 첫 end-to-end 기능 후보: Isoparametric 3D Euler beam element
 - 최소 Abaqus keyword subset:
   - `*HEADING`
   - `*NODE`
@@ -33,24 +33,17 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
   - `*ELSET`
   - `*MATERIAL`
   - `*ELASTIC`
-  - section keyword
+  - `*Beam General Section`
   - `*BOUNDARY`
   - `*CLOAD`
   - `*STEP`
   - `*STATIC`
   - output request subset
-- displacement 중심의 최소 `AnalysisState`
+- MKL PARDISO 기반 sparse direct solver
+- displacements, reactions, elemental forces 중심의 verification
 - HDF5 result schema v0
 - FESA HDF5 to Abaqus reference CSV comparison 계약
 
-## V1 범위
-- 2D plane stress/plane strain element
-- 3D solid element
-- MKL PARDISO 기반 sparse direct solve
-- TBB element-local computation 병렬화
-- reference model portfolio 확장
-- nonlinear static, dynamic, frequency, heat transfer 해석을 위한 interface 확장점
-
 ## 기능 요구조건
 | ID | 요구조건 | Acceptance Criteria | Verification Method |
 | --- | --- | --- | --- |
@@ -61,7 +54,7 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
 | FESA-PRD-005 | FESA는 해석 중 변하는 물리량을 `AnalysisState`에 저장해야 한다. | displacement, force, residual, increment/iteration 상태가 step/frame 출력과 연결된다. | state unit test, integration test |
 | FESA-PRD-006 | FESA는 solver 결과를 HDF5 authoritative output `results.h5`로 저장해야 한다. | step/frame, field/history, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test |
 | FESA-PRD-007 | FESA는 Abaqus reference CSV rows와 비교 가능한 deterministic row mapping을 제공해야 한다. | displacement, reaction, internal force, stress 등 검증 물리량의 row identity와 tolerance source가 명확하다. | reference comparison report |
-| FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file이 있고 Harness TDD guard를 통과한다. | hook test, CTest |
+| FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file, RED 실패와 후속 GREEN 성공 증거가 있고 Stop의 전체 MSVC build/test가 통과한다. | implementation report, Hook guardrail, CTest |
 | FESA-PRD-009 | FESA는 외부 라이브러리 API를 solver core에 직접 노출하지 않아야 한다. | MKL, TBB, HDF5 의존은 adapter module에 제한된다. | architecture review, dependency review |
 | FESA-PRD-010 | FESA 기능 완료는 reference comparison과 physics sanity 통과를 요구해야 한다. | 수치 tolerance와 물리 검토가 모두 pass이고 known limitation이 기록된다. | verification report, physics evaluation report |
 
@@ -79,7 +72,7 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
 2. Research evidence complete: 정식화와 benchmark 근거가 신뢰도와 한계와 함께 정리되어 있다.
 3. Formulation reviewed: 약형, shape function, B matrix, constitutive contract, 수치적분, output recovery가 검토되어 있다.
 4. I/O contract approved: Abaqus keyword subset, internal model mapping, HDF5 result contract, reference CSV comparison row contract가 승인되어 있다.
-5. Tests fail before implementation: 구현 전 실패해야 하는 C++/integration/reference test가 준비되어 있다.
+5. Tests fail before implementation: C++/integration/reference test를 제품 코드보다 먼저 작성하고 같은 Step 안에서 RED 실패와 후속 GREEN 성공을 확인한다.
 6. CMake/CTest pass: MSVC/x64/Debug 기준 configure, build, test가 통과한다.
 7. Reference comparison pass: FESA `results.h5` rows와 Abaqus reference CSV rows가 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준 안에 있다.
 8. Physics sanity pass: equilibrium, reaction consistency, displacement direction, symmetry, stress sanity가 검토되어 있다.
@@ -92,4 +85,3 @@ FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 유한요소법 기
 - GUI 또는 postprocessor
 - Visual Studio `.sln`/`.vcxproj` 전용 MSBuild workflow
 - Explicit dynamics, contact, plasticity, shell end-to-end 구현
-- JavaScript/TypeScript fallback 유지

docs/SOLVER_AGENT_DESIGN.md

@@ -12,6 +12,7 @@
 - Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference/<model-id>/`에 저장된 `model.inp`, `metadata.json`, Abaqus reference CSV files를 검증 기준으로 사용한다.
 - 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
 - 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
+- Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.
 
 ## 전체 Agent 구성
 
@@ -168,15 +169,20 @@ C++ 코드를 구현하는 Agent이다.
 빌드와 테스트를 실행하는 Agent이다.
 
 책임:
-- Harness validation을 실행한다.
+- `.harness/config.json` 또는 자동 감지 결과에 맞는 MSVC build/test 명령을 실행한다.
 - MSVC x64 Debug CMake configure/build/CTest 결과를 수집한다.
 - 실패 로그를 요약하고 Correction Agent에 전달한다.
 
-기본 검증 명령:
+기본 CMake 검증 명령:
 ```powershell
-python scripts/validate_workspace.py
+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
 ```
 
+Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 선언된 명령을 따른다.
+
 검증 대상:
 - CMake configure
 - MSVC Debug build
@@ -301,7 +307,8 @@ flowchart TD
 통과 조건:
 - CMake/MSVC/CTest validation이 통과한다.
 - 단위 테스트와 통합 테스트가 통과한다.
-- Harness TDD guard를 만족한다.
+- 관련 C++ test file이 있고 같은 구현 Step 안에 RED 실패와 후속 GREEN 성공 증거가 있다.
+- Stop의 전체 MSVC build/test 검증이 통과한다.
 
 ### Gate 5: 레퍼런스 검증
 통과 조건:
@@ -352,11 +359,12 @@ Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Defin
 ## 초기 적용 우선순위
 
 1. 선형 정적 해석의 최소 골격
-2. 1D truss 또는 bar element
-3. 2D plane stress/plane strain element
-4. 3D solid element
-5. material model 확장
-6. nonlinear 또는 dynamic analysis 확장
+2. Isoparametric 3D Euler beam element
+3. 1D truss 또는 bar element
+4. 2D plane stress/plane strain element
+5. 3D solid element
+6. material model 확장
+7. nonlinear 또는 dynamic analysis 확장
 
 각 단계는 요구조건, 정식화, 테스트모델, 구현, 레퍼런스 비교, 배포 Gate를 독립적으로 통과해야 한다.
 

docs/SOLVER_SKILL_DESIGN.md

@@ -15,7 +15,8 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 - Abaqus, Nastran 또는 reference solver 실행은 skill 범위에 포함하지 않는다.
 - Abaqus reference CSV 파일 생성/수정은 skill 범위에 포함하지 않는다.
 - C++ 구현 관련 skill은 C++17 이상, MSVC, CMake, CTest, TDD 원칙을 따른다.
-- 기본 workspace validation 명령은 `python scripts/validate_workspace.py`이다.
+- C++ 검증 명령은 `.harness/config.json` 또는 `docs/HARNESS.md`의 자동 감지 기본값을 따른다.
+- Harness Python 변경은 `uv run --with pytest python -m pytest -v -rs`로 검증한다.
 
 ## Skill 구성
 
@@ -34,10 +35,10 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 
 ## 개발 과정별 사용 예
 
-예시 기능: `linear-truss-1d`
+예시 기능: `isoparametric-3d-euler-beam`
 
 1. Requirement Agent는 `fesa-requirements-baseline`을 사용해 기능 범위, 제외 범위, 입력, 출력, 검증 물리량, tolerance, `Requirement Verification Matrix`를 작성한다.
-2. Research Agent는 `fesa-research-evidence`를 사용해 truss/bar element 이론, benchmark 후보, source reliability, applicability limits를 정리한다.
+2. Research Agent는 `fesa-research-evidence`를 사용해 3D Euler beam element 이론, benchmark 후보, source reliability, applicability limits를 정리한다.
 3. Formulation Agent는 `fesa-formulation-spec`을 사용해 strong form, weak form, shape functions, B matrix, element stiffness, output recovery를 정리한다.
 4. Numerical Review Agent는 `fesa-numerical-review`를 사용해 rigid body modes, patch test, stiffness symmetry, Jacobian, locking 위험을 검토하고 `pass-for-implementation-planning` 여부를 판단한다.
 5. I/O Definition Agent는 `fesa-io-contract`를 사용해 지원할 Abaqus `.inp` keyword subset, `results.h5` schema, reference CSV comparison row schema를 정의한다.
@@ -98,9 +99,17 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 - 기본 검증 명령:
 
 ```powershell
-python -m unittest discover -s scripts -p "test_*.py"
-python scripts/validate_workspace.py
-ctest -C Debug -R <feature-or-label>
+cmake -S . -B .harness/build -A x64
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`의 설정을 사용한다. Harness
+Python, Hook, agent config를 변경한 경우에는 다음 명령도 실행한다.
+
+```powershell
+uv run --with pytest python -m pytest -v -rs
 ```
 
 - 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다.
@@ -148,7 +157,8 @@ ctest -C Debug -R <feature-or-label>
 
 ## 검증 기준
 
-Skill 구성 검증은 `scripts/test_fesa_solver_skills.py`가 담당한다.
+Skill 구성은 실제 `.codex/skills/` 파일을 source of truth로 삼아 정적 계약과 repository
+pytest suite로 검증한다.
 
 검증 항목:
 
@@ -163,15 +173,11 @@ Skill 구성 검증은 `scripts/test_fesa_solver_skills.py`가 담당한다.
 검증 명령:
 
 ```powershell
-python -m unittest discover -s scripts -p "test_*.py"
-python scripts/validate_workspace.py
+uv run --with pytest python -m pytest -v -rs
 ```
 
-Skill 구조 검증:
-
-```powershell
-python C:\Users\user\.codex\skills\.system\skill-creator\scripts\quick_validate.py .codex\skills\<skill-name>
-```
+개별 skill schema를 점검할 때는 현재 Codex 설치에 포함된 `skill-creator` validator를
+사용하되 사용자 홈을 하드코딩한 경로를 프로젝트 계약으로 두지 않는다.
 
 ## v1 범위
 

docs/archive/ProjectInitialPlanNote.md

@@ -1,5 +1,10 @@
 # FESA 초기 문서 완성 계획 노트
 
+> **Historical / Superseded:** 이 문서는 2026-06-10 시점의 초기 조사와 실행 기록이다.
+> 현재 제품 범위는 `docs/PRD.md`, Harness 운영 계약은 `docs/HARNESS_WORKFLOW.md`와
+> `docs/HARNESS.md`를 따른다. 아래의 구형 스킬명, 검증 명령, 기능 우선순위는 현재
+> 지침으로 사용하지 않는다.
+
 ## 메타데이터
 - 작성일: 2026-06-10
 - 목적: `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`를 유한요소법 기반 구조해석 솔버 개발 프로젝트 문서로 완성하기 위한 조사 내용과 실행 계획 정리

docs/build-test-reports/README.md

@@ -2,16 +2,17 @@
 
 이 디렉터리는 Build/Test Executor Agent가 작성하거나 제안하는 기능별 build/test 실행 리포트를 보관하는 위치다.
 
-Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 C++/MSVC/CMake/CTest 검증을 실행하고, 실패를 분류해 다음 agent로 handoff한다. 이 agent는 source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다. build artifacts와 test outputs는 `build/` 아래 생성될 수 있다.
+Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 C++/MSVC/CMake/CTest 검증을 실행하고, 실패를 분류해 다음 agent로 handoff한다. 이 agent는 source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다. 기본 build artifact는 `.harness/build/` 아래 생성된다.
 
 기본 문서명은 `docs/build-test-reports/<feature-id>-build-test.md` 형식을 사용한다.
 
 ## Build/Test Executor Agent 역할
 
 수행한다:
-- `python scripts/validate_workspace.py`를 기본 검증 명령으로 실행한다.
-- implementation plan/report에 명시된 경우 harness self-test와 feature-specific CTest를 실행한다.
-- `HARNESS_VALIDATION_COMMANDS`, `CMakePresets.json`의 `msvc-debug`, 기본 CMake/MSVC x64 Debug 경로 중 어떤 검증 경로가 사용되었는지 기록한다.
+- `.harness/config.json`과 프로젝트 자동 감지 결과를 확인하고 같은 build/test 경로를 독립 실행한다.
+- implementation plan/report에 명시된 feature-specific CTest를 전체 검증 전에 실행한다.
+- Harness Python, Hook, agent config 변경이 포함되면 `uv run --with pytest python -m pytest -v -rs`를 실행한다.
+- CMake preset, 직접 MSBuild, 기본 CMake/MSVC x64 Debug 중 어떤 검증 경로가 사용되었는지 기록한다.
 - configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
 - command, exit code, duration, stdout/stderr tail, failed test name을 요약한다.
 - 실패 원인에 따라 Implementation Agent, Correction Agent, Reference Verification Agent, Implementation Planning Agent 중 handoff 대상을 제안한다.
@@ -28,29 +29,43 @@ Build/Test Executor Agent는 Implementation Agent 이후 독립적으로 C++/MSV
 
 ## 실행 순서
 
-기본 순서는 implementation plan/report에 따라 다음 중 필요한 항목만 실행한다.
+기본 순서는 implementation plan/report에 따라 다음 중 필요한 항목을 실행한다.
 
 ```powershell
-python -m unittest discover -s scripts -p "test_*.py"
-ctest -C Debug -R <feature-or-label>
-python scripts/validate_workspace.py
+cmake -S . -B .harness/build -A x64
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
 ```
 
-`scripts/validate_workspace.py`의 command discovery 우선순위는 다음과 같다.
+Harness Python, Hook, agent config 변경이 검증 범위에 포함되면 다음 명령을 먼저 실행한다.
 
-1. `HARNESS_VALIDATION_COMMANDS`
-2. `CMakePresets.json`의 `msvc-debug`
-3. 기본 CMake/MSVC x64 Debug 명령
-4. `CMakeLists.txt`가 없고 override도 없으면 안내 메시지와 함께 성공 종료
+```powershell
+uv run --with pytest python -m pytest -v -rs
+```
+
+프로젝트 선택 우선순위는 다음과 같다.
+
+1. `.harness/config.json`의 명시적 `projectType`
+2. 루트의 CMake metadata
+3. 루트의 단일 `.sln`
+4. 루트의 단일 `.vcxproj`
 
 기본 CMake/MSVC x64 Debug 명령은 다음과 같다.
 
 ```powershell
-cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
-cmake --build build/msvc-debug --config Debug
-ctest --test-dir build/msvc-debug --output-on-failure -C Debug
+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 preset을 사용하면 configure/build/test preset과 `binaryDir`를 모두
+`.harness/config.json`에 지정한다. 직접 MSBuild는 solution/project와
+`msbuild.testCommand`를 지정한다. C/C++와 build metadata가 모두 없으면 검증 대상이
+없으므로 통과하지만, C/C++ 파일만 있고 build metadata가 없으면 오류다.
+
 ## 문서 템플릿
 
 ```markdown
@@ -69,17 +84,19 @@ ctest --test-dir build/msvc-debug --output-on-failure -C Debug
 - generator: Visual Studio 17 2022 | <observed generator>
 - platform: x64 | <observed platform>
 - config: Debug | <observed config>
-- build_dir: build/msvc-debug | <observed build dir>
-- active_override_env_vars: HARNESS_VALIDATION_COMMANDS | HARNESS_CMAKE_GENERATOR | HARNESS_CMAKE_PLATFORM | HARNESS_CMAKE_CONFIG | HARNESS_BUILD_DIR | none
-- command_discovery_path: HARNESS_VALIDATION_COMMANDS | CMakePresets.json msvc-debug | default CMake/MSVC x64 Debug | no-CMake informational success
+- build_dir: .harness/build | <configured/observed build dir>
+- harness_config: .harness/config.json | absent-defaults
+- project_selection: configured cmake | configured msbuild | auto CMake | auto MSBuild | no C/C++ project
+- command_discovery_path: CMake preset | direct MSBuild | default CMake/MSVC x64 Debug | no C/C++ project
 
 ## Command Log Summary
 
 | order | command | exit_code | duration | stdout_stderr_tail |
 | --- | --- | --- | --- | --- |
-| 1 | python -m unittest discover -s scripts -p "test_*.py" | <code> | <duration> | <tail summary> |
-| 2 | ctest -C Debug -R <feature-or-label> | <code> | <duration> | <tail summary> |
-| 3 | python scripts/validate_workspace.py | <code> | <duration> | <tail summary> |
+| 1 | uv run --with pytest python -m pytest -v -rs (when applicable) | <code or skipped> | <duration> | <tail summary> |
+| 2 | <config-resolved configure/build commands> | <code> | <duration> | <tail summary> |
+| 3 | <feature-specific test command when applicable> | <code or skipped> | <duration> | <tail summary> |
+| 4 | <config-resolved test discovery/full test commands> | <code> | <duration> | <tail summary> |
 
 ## Validation Results
 
@@ -137,7 +154,7 @@ ctest --test-dir build/msvc-debug --output-on-failure -C Debug
 - 모든 실행 명령과 exit code를 기록해야 한다.
 - 실패 로그는 전체 원문을 복제하지 않고 마지막 핵심 구간과 실패 원인을 요약한다.
 - configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
-- no-CMake 상황은 `scripts/validate_workspace.py` 정책대로 안내 메시지와 성공 종료로 기록한다.
+- C/C++와 build metadata가 모두 없는 상황만 `no C/C++ project` 성공으로 기록한다. C/C++ 파일이 있는데 build metadata가 없으면 `environment` 또는 `configure` 실패로 기록한다.
 - 성공 판정은 build/test 통과까지만 의미한다.
 - reference tolerance, physics validation, release readiness는 판정하지 않는다.
 - upstream 계약 문제는 Implementation Agent에 임의 수정으로 넘기지 않고 적절한 upstream agent로 handoff한다.

docs/coordination/README.md

@@ -53,7 +53,7 @@ INTAKE -> STATE AUDIT -> GATE DECISION -> HANDOFF PACKAGE -> STATUS REPORT
 - Reference Verification Agent report
 - Physics Evaluation Agent report
 - Release Agent report
-- validation command evidence: `python scripts/validate_workspace.py`
+- Build/Test report의 `.harness/config.json` 또는 자동 감지 기반 MSVC build/test command evidence
 
 ## 문서 템플릿
 
@@ -184,6 +184,6 @@ INTAKE -> STATE AUDIT -> GATE DECISION -> HANDOFF PACKAGE -> STATUS REPORT
 
 ## 검증 기준
 
-- Coordinator Agent config와 문서 템플릿 검증은 Python unittest로 수행한다.
-- workspace 검증은 `python scripts/validate_workspace.py`를 사용한다.
-- 현재 repository에 CMake 프로젝트가 없으면 harness 정책에 따라 no-CMake validation 경로가 성공으로 기록될 수 있다.
+- Coordinator Agent config와 문서 템플릿에 자동화된 Python 검증이 있으면 `uv run --with pytest python -m pytest -v -rs`로 실행한다.
+- C++ build/test evidence는 `.harness/config.json` 또는 Harness 자동 감지 기본값에 따른 Build/Test report에서 확인한다.
+- C/C++ 파일과 build metadata가 모두 없을 때만 `no C/C++ project` 성공을 허용한다. C/C++ 파일만 있고 build metadata가 없으면 통과 evidence로 사용하지 않는다.

docs/corrections/README.md

@@ -12,8 +12,8 @@ Correction Agent는 Build/Test Executor Agent, Reference Verification Agent, Phy
 - 실패 로그와 implementation report를 읽고 failure classification을 먼저 확정한다.
 - configure, compile, link, test, reference-comparison, harness, environment, upstream-contract 실패를 구분한다.
 - implementation-owned failure에 한해 source/header/test/CMake를 최소 수정한다.
-- 수정 후 targeted command를 먼저 실행하고 `python scripts/validate_workspace.py`를 실행한다.
-- harness, hook, agent config 관련 수정에서는 `python -m unittest discover -s scripts -p "test_*.py"`도 실행한다.
+- 수정 후 targeted command를 먼저 실행하고 `.harness/config.json` 또는 자동 감지 기본값에 따른 전체 MSVC build/test를 실행한다.
+- Harness Python, Hook, agent config 관련 수정에서는 `uv run --with pytest python -m pytest -v -rs`도 실행한다.
 - 반복 실패 또는 upstream 계약 문제를 Coordinator Agent나 관련 upstream agent로 handoff한다.
 
 수행하지 않는다:
@@ -40,11 +40,16 @@ TRIAGE -> MINIMAL FIX -> VERIFY -> REPORT
 
 ```powershell
 <targeted command that reproduced the failure>
-python scripts/validate_workspace.py
-python -m unittest discover -s scripts -p "test_*.py"
+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
 ```
 
-`python -m unittest discover -s scripts -p "test_*.py"`는 harness, hook, agent config, Python validation behavior가 correction 범위에 포함될 때 실행한다.
+Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`의 설정을 따른다. Harness
+Python, Hook, agent config, Python validation behavior가 correction 범위에 포함될 때는
+`uv run --with pytest python -m pytest -v -rs`도 실행한다. Stop 검증은 응답 종료 전에
+같은 전체 프로젝트 검증을 다시 수행한다.
 
 ## Failure Classification
 
@@ -53,7 +58,7 @@ python -m unittest discover -s scripts -p "test_*.py"
 - `link`: linker, symbol resolution, target dependency 실패
 - `test`: CTest, unit, integration, parser/I/O, ordinary regression test 실패
 - `reference-comparison`: 저장된 reference artifact와 deterministic comparison 실패
-- `harness`: Python harness self-test, TDD guard, hook, validation script 실패
+- `harness`: Python Harness test, PreToolUse/Stop Hook, config loading, discovery, adapter validation 실패
 - `environment`: MSVC, CMake, Python, path, permission, generator, local dependency 문제
 - `upstream-contract`: requirements, formulation, I/O, reference artifact, tolerance, implementation plan 불일치 또는 누락
 
@@ -104,8 +109,8 @@ Excluded files:
 | order | command | exit_code | result | evidence |
 | --- | --- | --- | --- | --- |
 | 1 | <targeted command> | <code> | pass | fail | <summary> |
-| 2 | python scripts/validate_workspace.py | <code> | pass | fail | <summary> |
-| 3 | python -m unittest discover -s scripts -p "test_*.py" | <code or skipped> | pass | fail | skipped | <summary> |
+| 2 | <config-resolved full MSVC build/test commands> | <code> | pass | fail | <summary> |
+| 3 | uv run --with pytest python -m pytest -v -rs | <code or skipped> | pass | fail | skipped | <summary> |
 
 ## Traceability
 

docs/implementation-plans/README.md

@@ -15,7 +15,7 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
 - CMake/CTest target, `add_test`, label, `ctest -C Debug` 검증 계획을 정의한다.
 - candidate source/header/test/CMake 파일과 ownership boundary를 제안한다.
 - requirement, task, test, reference model, acceptance criterion을 Acceptance Traceability Matrix로 연결한다.
-- `python scripts/validate_workspace.py`를 포함한 validation command를 명시한다.
+- `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다.
 
 수행하지 않는다:
 - C++ 코드를 구현하지 않는다.
@@ -80,8 +80,8 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
 - add_test_needs: <CTest registration needs>
 - labels: unit | integration | reference | parser | io
 - msvc_config: Debug
-- expected_feature_command: ctest -C Debug -R <feature-or-label>
-- workspace_validation: python scripts/validate_workspace.py
+- expected_feature_command: ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
+- full_validation_source: .harness/config.json | Harness auto detection
 
 ## Candidate Files and Ownership
 
@@ -107,11 +107,17 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
 
 ## Validation Commands
 ```powershell
-python -m unittest discover -s scripts -p "test_*.py"
-python scripts/validate_workspace.py
-ctest -C Debug -R <feature-or-label>
+cmake -S . -B .harness/build -A x64
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
+ctest --test-dir .harness/build -C Debug --output-on-failure
 ```
 
+Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 해석 가능한 명령을 적는다.
+Harness Python, Hook, agent config 변경이 계획 범위에 포함되면
+`uv run --with pytest python -m pytest -v -rs`도 추가한다. Stop 검증은 Step 종료 전 전체
+MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를 대체하지 않는다.
+
 ## Risks and Downstream Handoff
 
 ### Implementation Agent

docs/releases/README.md

@@ -43,7 +43,7 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
 - Build/Test report status: `pass-for-reference-verification`
 - Implementation report와 implementation plan의 feature scope 일치
 - requirements, formulations, numerical reviews, I/O definitions, reference models 문서의 feature scope 일치
-- validation command evidence: `python scripts/validate_workspace.py`
+- Build/Test report의 `.harness/config.json` 또는 자동 감지 기반 MSVC build/test command evidence
 
 ## 문서 템플릿
 
@@ -99,8 +99,8 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
 
 | command_or_report | expected | observed | notes |
 | --- | --- | --- | --- |
-| python scripts/validate_workspace.py | pass | <result> | <summary> |
-| CMake/MSVC/CTest | pass | <result> | <summary> |
+| Build/Test report의 config-resolved CMake/MSVC/CTest | pass | <result> | <summary> |
+| Harness Python pytest (when applicable) | pass or N/A | <result> | <summary> |
 | reference verification | pass-for-physics-evaluation | <status> | <summary> |
 | physics evaluation | pass-for-release-agent | <status> | <summary> |
 

docs/superpowers/plans/2026-06-11-harden-execute-runner.md

@@ -1,5 +1,9 @@
 # Harden Execute Runner Implementation Plan
 
+> **Historical / Superseded:** 이 계획의 `codex/` 브랜치, `allowed_paths`, explicit
+> staging, 구형 workspace validation 계약은 현재 Runner 동작이 아니다. 현재 계약은
+> `docs/HARNESS_WORKFLOW.md`와 `docs/HARNESS.md`를 따른다.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Make `scripts/execute.py` safe enough to use by enforcing `codex/` branch names, clean starting state, explicit staging, per-step file allowlists, and validation before every runner-created commit.

docs/superpowers/plans/2026-06-11-reference-csv-comparison-contract.md

@@ -1,5 +1,10 @@
 # Reference CSV Comparison Contract Implementation Plan
 
+> **Historical / Partially Superseded:** Reference CSV/HDF5 제품 계약의 배경 기록으로만
+> 보존한다. 이 문서의 Python `unittest`, 삭제된 workspace validation script, Harness
+> 환경 변수 관련 검증 절차는 폐기되었으며 현재 운영 계약은
+> `docs/HARNESS_WORKFLOW.md`와 `docs/HARNESS.md`를 따른다.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Re-align FESA reference comparison contracts so FESA solver output remains authoritative HDF5, while Abaqus-derived reference results are CSV files compared directly against the FESA `results.h5` datasets.