FESADev/docs/SOLVER_SKILL_DESIGN.md

# FESA Solver Skill Design

## 목적

이 문서는 FESA의 8단계 feature workflow에서 사용하는 project-local skill 구성을 정의한다.
Agent는 역할과 책임 단위이고 skill은 여러 agent가 재사용하는 절차, 품질 gate와 handoff
단위다. 모든 feature별 skill output은 `docs/<feature-id>/`에 기록한다.

실제 실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`다. 이 문서는
skill inventory와 책임 분리를 사람이 읽을 수 있게 설명한다.

## 설계 원칙

- 각 skill은 `SKILL.md`의 `name`, `description` frontmatter와 `agents/openai.yaml` UI metadata를
  가진다.
- Skill은 입력, workflow, output contract, boundaries, quality gate와 handoff를 정의한다.
- 공통 상위 계약은 `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md`다.
- Abaqus, Nastran 또는 다른 reference solver 실행과 reference CSV 생성/수정은 skill 범위가
  아니다.
- C++ 절차는 C++17 이상, MSVC x64 Debug, CMake/CTest와 TDD를 따른다.
- 검증 명령은 `.harness/config.json`을 우선하고 없으면 `docs/HARNESS.md`의 자동 감지
  기본값을 따른다.
- Skill output path에는 agent별 폴더를 만들지 않고 `docs/<feature-id>/`만 사용한다.

## 8개 workflow skill

| Skill | 8단계 적용 과정 | 주요 사용자 sub-agent | `docs/<feature-id>/` 대표 산출물 |
| --- | --- | --- | --- |
| `fesa-requirements-baseline` | 1. 요구조건 | Requirement Agent | `requirements.md` |
| `fesa-research-evidence` | 2. 연구 | Research Agent | `research.md` |
| `fesa-formulation-spec` | 3. 정식화 | Formulation Agent | `formulation.md` |
| `fesa-numerical-review` | 4. 수치 검토 + reference readiness | Numerical Review Agent | `numerical-review.md`, `reference-model.md` |
| `fesa-io-contract` | 5. I/O 정의 | I/O Definition Agent | `io.md` |
| `fesa-cpp-msvc-tdd` | 6. 구현 계획 + C++ 구현 + build/test + reference comparison | Implementation Planning Agent, Implementation Agent, Correction Agent | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md`, 필요 시 `corrections.md` |
| `fesa-physics-sanity` | 7. 물리 검토 | Physics Evaluation Agent | `physics-evaluation.md` |
| `fesa-release-readiness` | 8. 배포 준비 | Release Agent | `release.md` |

통합 후 FESA workflow skill은 위 8개가 전부다.

## Skill별 핵심 계약

### `fesa-requirements-baseline`

- 기능 요청을 검증 가능한 baseline으로 만든다.
- `shall` 문장과 `FESA-REQ-<FEATURE>-###` id를 사용한다.
- 모든 `must` 요구조건에 verification method와 acceptance criteria를 연결한다.
- FEM 정식화, C++ 구현, reference value 생성 또는 release 판정은 하지 않는다.

### `fesa-research-evidence`

- Research question, source inventory, reliability tier, benchmark 후보와 applicability limit를
  정리한다.
- 검증된 사실과 추론을 분리하고 source gap은 open issue로 남긴다.
- FEM 정식화나 reference value를 확정하지 않는다.

### `fesa-formulation-spec`

- Strong form, weak form, discretization, kinematics, constitutive contract와 element equation을
  구분한다.
- Jacobian, derivative transform, numerical integration, output recovery와 numerical risk를
  명시한다.
- C++ API, parser ownership 또는 file layout을 설계하지 않는다.
- Numerical Review 전에는 최종 구현 승인 상태로 두지 않는다.

### `fesa-numerical-review`

이 skill은 numerical correctness와 reference readiness 절차를 함께 소유한다.

```text
FORMULATION REVIEW -> REFERENCE CASE INVENTORY -> CLASSIFY -> REPORT -> I/O HANDOFF
```

- Dimensions, signs, DOF order, coordinate transform, Jacobian, integration, stiffness symmetry,
  rigid-body mode, patch test, hourglass와 locking을 독립 검토한다.
- 기존 exact input/required CSV를 inventory하고 blocking/warning quantity, source identity와
  component matching, missing/extra/duplicate/nonfinite row precheck와 승인 tolerance를 정한다.
- `numerical-review.md`와 `reference-model.md`를 함께 산출한다.
- Logical quantity와 source identity까지만 정의한다. 최종 HDF5 dataset projection은 I/O
  Definition Agent에 handoff한다.
- 두 문서가 준비된 `pass-for-io-definition`만 다음 단계 진행을 허용한다.

### `fesa-io-contract`

- 지원할 Abaqus `.inp` keyword subset, semantic model mapping과 validation rule을 정의한다.
- Authoritative `results.h5` schema, units, coordinates, step/frame, row identity와 component를
  정의한다.
- Reference readiness의 logical quantity/source identity를 최종 HDF5 dataset projection과
  CSV column mapping으로 연결한다.
- Parser 구현이나 full Abaqus compatibility를 주장하지 않는다.

### `fesa-cpp-msvc-tdd`

이 skill은 implementation planning, TDD implementation, MSVC validation, failure correction과
reference comparison 절차를 함께 소유한다.

```text
RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY
    -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK
    -> COMPARE -> CLASSIFY -> REPORT
```

- Planning 시 project-local `harness`로 user-approved multi-Step plan을 만들고
  `implementation-plan.md`를 산출한다.
- C++ production 변경에는 관련 C++ test가 있어야 하며 targeted RED와 후속 GREEN evidence를
  기록한다.
- `.harness/config.json`이 선택한 MSVC x64 Debug build/CTest를 실행하고 명령, exit code,
  duration, output tail과 failure classification을 `build-test.md`에 기록한다.
- Reference artifact check 뒤 HDF5/CSV row를 source identity와 component로 대응시킨다.
  Missing, extra, duplicate와 nonfinite required row는 tolerance 전에 실패하며 warning-only
  quantity는 blocking result를 바꾸지 않는다.
- Implementation-owned 실패를 먼저 수정한다. 반복되거나 불명확한 실패는 Coordinator를
  통해 Correction Agent로 보내고 `corrections.md`에 재작업 evidence를 남긴다.
- 성공 시 `implementation-report.md`, `build-test.md`, `reference-comparison.md`와
  `pass-for-physics-evaluation` handoff를 반환한다.
- Requirements, formulation, numerical/reference 계약, I/O 계약, reference artifact 또는
  tolerance policy를 변경해 결과를 맞추지 않는다.

기본 validation sequence는 다음과 같다.

```powershell
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
```

### `fesa-physics-sanity`

- Implementation gate 통과 후 equilibrium, reaction consistency, displacement direction,
  symmetry, element force balance, stress/strain sanity, rigid-body mode와 model coverage를
  검토한다.
- 문서화된 물리 기대값이 없으면 pass를 선언하지 않는다.
- `pass-for-release-agent`는 Release Agent 검토 가능 상태만 의미한다.

### `fesa-release-readiness`

- `GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT` 순서를 따른다.
- Requirements부터 physics까지 동일 feature evidence와 필수 pass status를 확인한다.
- Known limitations, Release Notes Draft와 `ready-for-release` 여부를 기록한다.
- 사용자 요청 없이 publish, deploy, package, tag, commit 또는 external release를 수행하지
  않는다.

## Supporting skills

다음은 8개 workflow skill 수에 포함하지 않는 supporting skill이다.

- `fem-theory-query`: FEM wiki의 이론, benchmark, solver manual과 verification evidence 조회.
- project-local `harness`: Implementation Planning의 Step 초안, 사용자 승인 후 phase
  materialization과 별도 요청에 의한 executor 실행.
- `review`: AGENTS, architecture, tests와 build requirement에 대한 repository change review.

Implementation Planning Agent는 project-local `harness`를 반드시 사용한다. 사용자에게
자기완결적 Step 초안을 먼저 제시하고 승인 후에만 `phases/index.json`,
`phases/<task-name>/index.json`, `phases/<task-name>/stepN.md`를 생성한다. `scripts/execute.py`는
별도 사용자 요청 없이 실행하지 않는다.

## Agent와 skill 관계

| Agent | 주로 사용하는 skill |
| --- | --- |
| Coordinator Agent | 단계 owner가 반환한 skill evidence를 audit하고 dispatch/closure 관리 |
| Requirement Agent | `fesa-requirements-baseline` |
| Research Agent | `fesa-research-evidence`, 필요 시 `fem-theory-query` |
| Formulation Agent | `fesa-formulation-spec` |
| Numerical Review Agent | `fesa-numerical-review`, 필요 시 `fem-theory-query` |
| I/O Definition Agent | `fesa-io-contract` |
| Implementation Planning Agent | project-local `harness`, `fesa-cpp-msvc-tdd` |
| Implementation Agent | `fesa-cpp-msvc-tdd` |
| Correction Agent | `fesa-cpp-msvc-tdd` |
| Physics Evaluation Agent | `fesa-physics-sanity` |
| Release Agent | `fesa-release-readiness` |

## 검증 기준

Skill 구성은 실제 `.codex/skills/` 파일과 repository pytest suite를 기준으로 검증한다.

- 8개 FESA workflow skill의 `SKILL.md` 존재 여부
- YAML frontmatter의 `name`, `description`
- 공통 section: `Inputs`, `Workflow`, `Output Contract`, `Boundaries`, `Quality Gate`, `Handoff`
- `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md` 참조
- Skill-specific procedure와 `docs/<feature-id>/` output contract
- `agents/openai.yaml` UI metadata와 skill name reference
- TOML 및 YAML metadata parseability

Repository validation은 다음 명령을 사용한다.

```powershell
uv run --with pytest python -m pytest -v -rs
```

개별 skill schema는 현재 Codex 설치의 `skill-creator` validator로 점검하되 사용자 홈의
절대 경로를 프로젝트 계약으로 두지 않는다.