docs: align guidance with simplified agent and harness workflow

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-name>/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-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`으로 반환한다.
+## 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를 강제하지 않는다. 정적 검토와 실제 실행 여부를 구분해 기록한다.