modify documents

2026-09-05 15:14:21 +09:00
parent 31dac85192
commit 97e4d7a971
79 changed files with 4570 additions and 2787 deletions
@@ -1,193 +1,165 @@
-# FESA Solver Skill Design
+# Structural FEM Solver Skill Design

-## 목적
+## 1. 목적

-이 문서는 FESA의 8단계 feature workflow에서 사용하는 project-local skill 구성을 정의한다.
-Agent는 역할과 책임 단위이고 skill은 여러 agent가 재사용하는 절차, 품질 gate와 handoff
-단위다. 모든 feature별 skill output은 `docs/<feature-id>/`에 기록한다.
+Project-local skill은 범용 유한요소 구조해석 solver feature를 요구사항부터 release readiness까지
+일관되게 처리하는 재사용 절차다. Agent가 stage의 책임과 write boundary를 소유하고, skill은
+그 stage에서 필요한 판단 방법, evidence와 output contract를 제공한다.

-실제 실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`다. 이 문서는
-skill inventory와 책임 분리를 사람이 읽을 수 있게 설명한다.
+실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`다. 공통 workflow와
+상태 전이는 `docs/SOLVER_AGENT_DESIGN.md`, 수치 비교 정책은 `docs/TOLERANCE.md`가 소유한다.
+Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다.

-## 설계 원칙
+## 2. 설계 원칙

- 각 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>/`만 사용한다.
+- 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다.
+- `SKILL.md`에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다.
+- 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 `references/`에서 필요한
+  경우에만 읽는다.
+- Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다.
+- 산출물은 Coordinator가 생성·관리하는 `docs/<feature-id>/`의 공통 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`으로 반환한다.

-## 8개 workflow skill
+## 3. Workflow skill inventory

-| 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` |
+| Stage | 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` |

-통합 후 FESA workflow skill은 위 8개가 전부다.
+위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter `name`, agent prompt와
+`agents/openai.yaml` invocation name은 항상 동일해야 한다.

-## Skill별 핵심 계약
+## 4. Stage별 책임 분리

-### `fesa-requirements-baseline`
+### Requirements

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

-### `fesa-research-evidence`
+### Research

- Research question, source inventory, reliability tier, benchmark 후보와 applicability limit를
-  정리한다.
- 검증된 사실과 추론을 분리하고 source gap은 open issue로 남긴다.
- FEM 정식화나 reference value를 확정하지 않는다.
+`fem-research-evidence`는 governing theory, primary source, benchmark와 reference convention의
+신뢰성·적용 한계를 정리한다. 사실, 계산, 추론과 evidence gap을 구분하며 formulation 결론을
+대신 만들지 않는다.

-### `fesa-formulation-spec`
+### Formulation

- 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 전에는 최종 구현 승인 상태로 두지 않는다.
+`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만 읽는다.

-### `fesa-numerical-review`
+### Numerical review

-이 skill은 numerical correctness와 reference readiness 절차를 함께 소유한다.
+`fem-numerical-review`는 formulation을 독립 검토하고 requirement를 falsify할 verification
+coverage를 정의한다. Logical quantity, identity, location, units와 tolerance 근거까지 소유하지만
+physical dataset/file layout은 I/O stage에 남긴다.

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

- 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`만 다음 단계 진행을 허용한다.
+`fem-io-contract`은 선택된 external syntax와 semantic model, versioned result schema 및
+comparison identity 사이를 mapping한다. 미지원 semantic construct, validation과 diagnostic을
+명시한다. Subset 지원을 full compatibility로 표현하지 않는다.

-### `fesa-io-contract`
+### Planning, implementation와 correction

- 지원할 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를 주장하지 않는다.
+`fem-implementation-tdd`는 approved upstream bundle을 작은 RED/GREEN step으로 계획하고 C++
+변경, configured build/test와 필요한 reference comparison evidence를 만든다. Implementation은
+upstream contract, tolerance 또는 reference artifact를 결과에 맞춰 고치지 않는다.

-### `fesa-cpp-msvc-tdd`
+Executor의 process/session 재시도는 transport attempt이며 Coordinator의 normalized
+failure/correction budget과 별개다. 동일 `retry_key`의 correction은 한 번만 허용한다.

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

-```text
-RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY
-    -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK
-    -> COMPARE -> CLASSIFY -> REPORT
-```
+`fem-physics-review`는 numerically passing result가 문서화된 equilibrium, sign, symmetry,
+energy, mode와 model coverage 기대를 만족하는지 독립 검토한다. 새 acceptance를 즉석에서
+만들지 않는다.

- 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를 변경해 결과를 맞추지 않는다.
+### Release readiness

-기본 validation sequence는 다음과 같다.
+`fem-release-readiness`는 동일 feature/contract revision의 traceability, gate evidence,
+limitations와 release-note draft를 감사한다. Readiness verdict는 publish, tag, deploy 또는
+external release 권한이 아니다.

-```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
-```
+## 5. Supporting skill

-### `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 |
+| 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` |
+| `fem-theory-query` | 사용자가 configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때 |
+| `harness` | implementation phase를 만들거나 bounded Executor 작업을 수행할 때 |
+| `review` | repository diff를 architecture, numerical, test와 evidence 기준으로 읽기 전용 검토할 때 |

-## 검증 기준
+`fem-theory-query`는 일반 FEM 질문 전체를 가로채지 않는다. Vault path는 environment,
+project instruction 또는 untracked local override에서 해석하며 workstation 절대 경로를
+commit하지 않는다. External research나 vault write는 해당 요청과 권한이 있을 때만 수행한다.

-Skill 구성은 실제 `.codex/skills/` 파일과 repository pytest suite를 기준으로 검증한다.
+Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은
+guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다.

- 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
+## 6. 공통 evidence

-Repository validation은 다음 명령을 사용한다.
+Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다.

-```powershell
-uv run --with pytest python -m pytest -v -rs
-```
+- `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

-개별 skill schema는 현재 Codex 설치의 `skill-creator` validator로 점검하되 사용자 홈의
-절대 경로를 프로젝트 계약으로 두지 않는다.
+필요한 명령이 실패했거나 실행되지 않았고 blocking evidence가 stale/missing이면 `pass`를
+반환하지 않는다. Raw log 전체를 모든 skill 문서에 복사하지 않고 재현 가능한 digest와 원본
+artifact path를 남긴다.
+
+## 7. Abaqus reference policy
+
+Abaqus는 project가 선택한 경우 다음 공개 observable convention의 기준으로 사용한다.
+
+- input keyword와 option의 문서화된 syntax/semantics
+- model data와 history/step data의 구분
+- element formulation, integration과 output location 정의
+- analysis procedure와 convergence 개념
+- verification guide의 benchmark 구성과 expected physical behavior
+
+Skill은 비공개 내부 구현을 추정하지 않고 full compatibility나 solver equivalence를 주장하지
+않는다. External Abaqus execution은 저장된 artifact를 읽는 것과 다른 권한이며 라이선스,
+자격증명, 비용과 명시된 command scope가 확보된 경우에만 수행한다.
+
+## 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 부재 또는 미실행을 성공으로 간주하지 않는다.