modify documents

docs/FEATURE_DOCUMENTATION.md

@@ -0,0 +1,79 @@
+# Feature 문서 관리
+
+이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
+`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
+`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.
+
+## 시작과 참조
+
+1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를
+   재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다.
+2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용
+   기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다.
+3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고
+   자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는
+   `AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다.
+4. 기존 `docs/features/<feature-id>/` 자료는 이력이므로 자동 이동하거나 복제하지 않는다.
+   재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다.
+
+이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
+기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
+Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
+계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.
+
+## Coordinator 관리 문서
+
+| 문서 | 필요한 내용 | 참조 기준 |
+| --- | --- | --- |
+| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` |
+| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 |
+| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 |
+| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 |
+
+- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를
+  가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다.
+  현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다.
+- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에
+  결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로
+  표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다.
+- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다.
+  Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다.
+- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를
+  갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다.
+- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자
+  요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.
+
+## Agent 산출물 작성
+
+각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
+필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.
+
+1. 식별: Feature ID, owner, 입력 contract revision.
+2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
+3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
+4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.
+
+상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
+수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
+분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.
+
+긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
+`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
+`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.
+
+- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
+  적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
+- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
+  기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
+- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
+  문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
+- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
+  기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
+  참조한다.
+
+## Gate 확인
+
+Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
+판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
+필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
+검증을 대신하지 않는다.

docs/SOLVER_AGENT_DESIGN.md

@@ -1,176 +1,220 @@
-# FESA Solver Agent Design
+# Structural FEM Solver Agent Design
 
-## 목적과 범위
+## 1. 목적
 
-이 문서는 FESA 기능 개발을 조정하는 agent 계층, 8단계 workflow, gate와 산출물 계약을
-정의한다. `coordinator-agent`가 유일한 main agent이며, 나머지 10개 profile은 Coordinator가
-호출하는 sub-agent다. 모든 기능별 agent 산출물은 `docs/<feature-id>/`에 모은다.
+이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
+`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
+산출물만 소유한다. 기능별 문서는 `docs/<feature-id>/`에 보존한다.
+폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는
+[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다.
 
-이 workflow는 개발 운영 계약이다. Solver C++ 아키텍처, CMake/CTest target, Harness
-executor와 hook, Abaqus reference artifact 또는 승인된 FEM 기능 의미를 바꾸지 않는다.
+이 계약의 목표는 다음과 같다.
 
-## Agent 계층
+- 수치적·물리적 책임을 명확히 분리한다.
+- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다.
+- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다.
+- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다.
+- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다.
 
-### Coordinator Agent: main-agent orchestration
+## 2. 권한과 판단 기준
 
-Coordinator Agent는 기능 요청을 접수하고 다음 실행 loop를 소유한다.
+충돌하는 정보는 다음 우선순위로 판단한다.
+
+1. 사용자가 승인한 feature contract와 critical decision
+2. 지배 방정식, 수학적 일관성, 적용되는 표준과 검증된 1차 문헌
+3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 verification 사례
+4. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md`와 기존 승인 계약
+5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현
+
+Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석
+절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료
+구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다.
+관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다.
+
+공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이
+입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로
+진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다.
+
+## 3. 계층과 단독 상태 전이
+
+`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다.
 
 ```text
-INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
-       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT
+INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
 ```
 
-- `docs/<feature-id>/coordination.md`의 8단계 worklist와 현재 workflow state를 관리한다.
-- 한 번에 다음 유효 단계의 owner만 bounded task로 dispatch한다.
-- 반환된 산출물 경로, status, evidence와 blocker를 검토한 뒤에만 gate를 전환한다.
-- Specialist 판단이나 C++ 구현을 대신하지 않으며, evidence 없이 gate를 통과시키지 않는다.
-- 동일한 normalized failure classification이 두 번 발생하면 자동 재작업을 멈추고
-  `needs-user-decision` 또는 `blocked`로 전환한다.
-- Release evidence가 `ready-for-release`일 때 최종 closure를 기록한다.
+- Coordinator는 요구사항 접수 시 Feature 폴더와 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`,
+  `coordination.md`를 생성하고 문서 목록과 참조를 관리한다. 프로젝트 기준 문서는 보존한다.
+- Coordinator만 `docs/<feature-id>/coordination.md`의 현재 stage, outcome과 next owner를 바꾼다.
+- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다.
+- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다.
+- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한
+  후 기록한다.
+- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다.
+- 누락된 증거는 통과로 간주하지 않는다.
 
-Worklist item은 `pending | in-progress | passed | needs-rework | blocked`만 사용한다.
-Sub-agent는 전달받은 단계와 산출물만 처리하며 peer를 호출하거나 다음 단계로 진행하지
-않는다. 완료 시 output paths, status, evidence summary와 blockers를 Coordinator에 반환한다.
+## 4. 단계와 소유권
 
-## 10개 sub-agent 역할
+| Stage | Owner | Owned outputs |
+| --- | --- | --- |
+| intake / coordination | `coordinator-agent` | `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md` |
+| `requirements` | `requirement-agent` | `requirements.md` |
+| `research` | `research-agent` | `research.md` |
+| `formulation` | `formulation-agent` | `formulation.md` |
+| `numerical-review` | `numerical-review-agent` | `numerical-review.md`, `reference-model.md` |
+| `io-definition` | `io-definition-agent` | `io.md` |
+| `implementation-planning` | `implementation-planning-agent` | `implementation-plan.md`, assigned Harness phase files |
+| `implementation` | `implementation-agent` | implementation files, tests, build registration, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
+| `physics-evaluation` | `physics-evaluation-agent` | `physics-evaluation.md` |
+| `release-readiness` | `release-agent` | `release.md` |
 
-### Requirement Agent
+`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
+implementation-owned 파일과 `corrections.md`를 수정한다.
 
-검증 가능한 범위, 제외 범위, `shall` 요구조건, acceptance criteria, verification quantity와
-tolerance baseline을 `requirements.md`에 정의한다.
+문서 경로는 모두 `docs/<feature-id>/` 기준이다. 각 specialist는 자신의 기본 산출물에
+연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며
+specialist 본문의 편집 권한을 뜻하지 않는다.
 
-### Research Agent
+각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
+재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
+`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.
 
-이론, solver manual, benchmark와 source reliability를 조사하고 확인된 사실과 추론 및
-applicability limit를 `research.md`에 분리해 기록한다.
+## 5. 공통 handoff envelope
 
-### Formulation Agent
+모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
+envelope에는 전이에 필요한 요약만 둔다.
 
-Strong/weak form, kinematics, constitutive contract, shape functions, element equation, numerical
-integration과 output recovery를 구현 가능한 수치 계약으로 `formulation.md`에 작성한다.
-
-### Numerical Review Agent
-
-독립적인 formulation 검토와 reference readiness를 하나의 merged gate로 소유한다. 차원,
-부호, DOF 순서, 좌표 변환, Jacobian, 적분, 대칭성, rigid-body mode, locking과 검증 위험을
-`numerical-review.md`에 기록한다. 동시에 exact reference input/CSV, blocking/warning quantity,
-source identity/component, row precheck와 승인 tolerance를 `reference-model.md`에 정의한다.
-두 문서가 모두 준비되어야 I/O 단계로 handoff할 수 있다.
-
-### I/O Definition Agent
-
-승인된 Abaqus `.inp` subset, semantic model mapping, validation diagnostic, authoritative
-`results.h5` schema와 reference CSV row schema를 `io.md`에 정의한다. Numerical/reference
-gate가 확정한 logical quantity와 source identity를 최종 HDF5 dataset projection 및 CSV
-column mapping으로 연결하는 책임은 이 agent에 있다.
-
-### Implementation Planning Agent
-
-승인된 upstream bundle을 자기완결적 TDD Step으로 분해해 `implementation-plan.md`를 만든다.
-계획 요청에서는 project-local `harness`를 사용하고 사용자에게 multi-Step 초안을 먼저
-제시한다. 승인 후에만 phase index와 `stepN.md`를 materialize하며 executor는 별도 명시
-요청이 있을 때만 실행한다.
-
-### Implementation Agent
-
-승인된 Step 단위로 `RED -> observed failure -> minimal GREEN -> focused VERIFY`를 수행하고,
-full MSVC x64 Debug build/CTest와 reference comparison까지 하나의 Implementation gate에서
-완료한다. `implementation-report.md`, `build-test.md`, `reference-comparison.md`를 각각 남기며
-최종 성공 status는 `pass-for-physics-evaluation`이다.
-
-### Correction Agent
-
-정규 단계가 아닌 on-demand rework sub-agent다. 같은 실패가 반복되거나 원인이 불명확할
-때 Coordinator가 호출한다. Upstream 계약을 바꾸지 않고 최소 수정과 재검증을 수행해
-`corrections.md`에 누적하고 Implementation Agent 재실행 요청을 Coordinator에 반환한다.
-
-### Physics Evaluation Agent
-
-Reference comparison 이후 equilibrium, reaction consistency, displacement direction, symmetry,
-element force balance, stress/strain sanity, rigid-body mode와 model coverage를 검토해
-`physics-evaluation.md`에 기록한다.
-
-### Release Agent
-
-Requirements부터 physics까지 gate evidence와 acceptance traceability를 audit하고 known
-limitations, release notes draft와 release verdict를 `release.md`에 기록한다. 내부 readiness
-판정은 publish, deploy, package, tag 또는 external release 권한이 아니다.
-
-## 8단계 개발 프로세스
-
-| 단계 | 담당 sub-agent | 필수 skill | `docs/<feature-id>/` 산출물 | 통과 조건 |
-| --- | --- | --- | --- | --- |
-| 1. 요구조건 | `requirement-agent` | `fesa-requirements-baseline` | `requirements.md` | 승인 범위, acceptance criteria, 검증량과 tolerance가 명확함 |
-| 2. 연구 | `research-agent` | `fesa-research-evidence`, 필요 시 `fem-theory-query` | `research.md` | 이론과 검증 evidence 및 적용 한계가 충분함 |
-| 3. 정식화 | `formulation-agent` | `fesa-formulation-spec` | `formulation.md` | 구현 가능한 수치 계약이 완성됨 |
-| 4. 수치 검토 + reference model 계약 | `numerical-review-agent` | `fesa-numerical-review` | `numerical-review.md`, `reference-model.md` | 두 문서가 함께 `pass-for-io-definition`임 |
-| 5. I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `io.md` | Logical reference identity가 최종 HDF5 projection과 연결됨 |
-| 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` | TDD, full MSVC/CTest와 blocking reference comparison이 모두 통과함 |
-| 7. 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `physics-evaluation.md` | 물리 검토가 `pass-for-release-agent`임 |
-| 8. 배포 준비 | `release-agent` | `fesa-release-readiness` | `release.md` | `ready-for-release`이며 Coordinator가 closure를 기록함 |
-
-## 8단계 workflow
-
-```mermaid
-flowchart TD
-  C["Coordinator: intake 및 worklist"] --> RQ["1. Requirement Agent"]
-  RQ --> RS["2. Research Agent"]
-  RS --> FM["3. Formulation Agent"]
-  FM --> NR["4. Numerical Review Agent<br/>numerical + reference gate"]
-  NR --> IO["5. I/O Definition Agent<br/>final HDF5 projection"]
-  IO --> IP["6. Implementation Planning Agent"]
-  IP --> IM["6. Implementation Agent<br/>TDD + MSVC/CTest + reference comparison"]
-  IM --> OK{"Implementation gate pass?"}
-  OK -- "yes" --> PH["7. Physics Evaluation Agent"]
-  OK -- "repeated or unclear failure" --> CR["Correction Agent<br/>on-demand rework"]
-  CR --> IM
-  PH --> RL["8. Release Agent"]
-  RL --> CL["Coordinator: closure"]
+```yaml
+feature_id: <stable feature id>
+stage: requirements | research | formulation | numerical-review | io-definition |
+  implementation-planning | implementation | correction | physics-evaluation |
+  release-readiness
+outcome: pass | return-upstream | retry | blocked-environment | needs-user-decision
+next_owner: <agent id or null>
+evidence_paths: [<repository-relative path>]
+evidence_digest: <commands, exit codes, decisive findings, artifact hashes when relevant>
+failure_classification: <normalized class or null>
+retry_key: <feature-id|failing-gate|classification|contract-revision or null>
+attempt: <nonnegative integer>
+escalation_class: <critical class or null>
+blocker: <actionable blocker or null>
 ```
 
-Compile, link, ordinary test와 명확한 implementation-owned mismatch는 Implementation Agent가
-먼저 수정한다. 반복되거나 불명확한 실패만 Correction loop로 보낸다. Upstream contract
-gap은 Coordinator가 해당 owner 단계로 되돌린다.
+필드 규칙은 다음과 같다.
 
-## Gate 계약
+- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다.
+- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다.
+- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다.
+- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다.
+- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다.
+- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다.
+- Dispatch는 `docs/<feature-id>/`와 Feature 관리 문서 3개를 필수 입력으로 명시한다.
+  기본·상세 산출물의 owner를 지정하고 반환된 상세 문서도 `evidence_paths`로 확인한다.
 
-1. Requirements gate: `requirements.md`가 범위, acceptance criteria, 검증량과 tolerance를
-   고정한다.
-2. Research gate: `research.md`가 필요한 이론, benchmark와 applicability evidence를 제공한다.
-3. Formulation gate: `formulation.md`가 구현 가능한 수치 계약을 제공한다.
-4. Numerical/reference merged gate: `numerical-review.md`와 `reference-model.md`가 함께 통과한다.
-5. I/O gate: `io.md`가 source identity와 logical quantity를 authoritative `results.h5` dataset,
-   units, coordinates, component와 CSV column에 최종 투영한다.
-6. Implementation gate: 승인 계획, RED/GREEN/VERIFY evidence, full MSVC x64 Debug build/CTest,
-   deterministic row precheck와 blocking/warning reference comparison이 모두 통과한다.
-7. Physics gate: `physics-evaluation.md`가 `pass-for-release-agent`다.
-8. Release gate: `release.md`가 `ready-for-release`이고 Coordinator가 closure를 기록한다.
+## 6. Outcome과 전이 규칙
 
-Reference comparison은 source identity와 component로 행을 결정적으로 대응시키며 missing,
-extra, duplicate 또는 nonfinite required row를 tolerance 전에 거부한다. CSV는 외부 reference이고
-FESA의 authoritative output은 `results.h5`다. 공통 tolerance 값, family 구성, row/RMS
-판정, report evidence와 변경 관리는 `docs/TOLERANCE.md`를 따른다.
+| Outcome | 의미 | Coordinator action |
+| --- | --- | --- |
+| `pass` | 현재 owner의 gate evidence가 완전함 | 다음 정규 stage로 전이 |
+| `return-upstream` | 선행 계약의 수정이 필요함 | `next_owner`로 되돌리고 영향받은 downstream gate를 stale 처리 |
+| `retry` | 계약을 바꾸지 않는 bounded rerun이 가능함 | retry 정책 안에서 지정 owner를 재호출 |
+| `blocked-environment` | 도구·권한·의존성·라이선스 문제로 신뢰성 있는 진행 불가 | 상태를 보존하고 환경 수정 전까지 중단 |
+| `needs-user-decision` | 아래 critical decision이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 |
 
-## 요구사항 단위 산출물 구조
+`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지
+않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만
+사용한다.
+
+정규 통과 순서는 다음과 같다.
 
 ```text
-docs/<feature-id>/
-├── coordination.md
-├── requirements.md
-├── research.md
-├── formulation.md
-├── numerical-review.md
-├── reference-model.md
-├── io.md
-├── implementation-plan.md
-├── implementation-report.md
-├── build-test.md
-├── reference-comparison.md
-├── corrections.md
-├── physics-evaluation.md
-└── release.md
+requirements -> research -> formulation -> numerical-review -> io-definition
+-> implementation-planning -> implementation -> physics-evaluation
+-> release-readiness -> completed
 ```
 
-산출물이 필요하지 않았거나 기존 workflow에 없었던 경우 placeholder를 만들지 않는다.
-`corrections.md`는 실제 on-demand correction이 발생했을 때만 생성한다. Reference input/CSV는
-현재 path와 name 그대로 read-only로 사용하고, 문서 정리를 위해 rename 또는 보정하지 않는다.
+Numerical review는 formulation correctness와 reference-model readiness가 모두 확보되어야
+`pass`할 수 있다. Implementation은 TDD evidence, 전체 build/test와 feature가 요구하는
+reference comparison이 모두 통과해야 `pass`할 수 있다. Release의 `pass`는 내부 readiness
+closure일 뿐 publish, deploy, push, tag 또는 package 권한이 아니다.
+
+## 7. 자율 진행과 사용자 escalation
+
+Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다.
+
+- 승인 계약을 구현하는 파일 배치, private API와 내부 자료구조 선택
+- 기존 규칙에 따른 테스트 분해, config-selected build/test backend 등록, 진단 문구와 오류 처리
+- 문서·계획·evidence report의 생성 및 갱신
+- 명백한 compile, link, test, parser와 implementation defect의 최소 수정
+- Numerical Review가 `docs/TOLERANCE.md`와 feature evidence에 따라 선택하는 비교 quantity,
+  identity/component, metric, scale, blocking/diagnostic 구분과 수치 tolerance
+- 공식 문서와 저장소 관례가 하나의 의미를 정하는 secondary convention
+- 안전한 read-only 조사, local build/test와 저장된 reference artifact 비교
+
+다음 항목만 `needs-user-decision`으로 escalation한다.
+
+- feature scope, 지원 해석 유형 또는 공개 호환성의 변경
+- 지배 방정식, 요소 정식화, 재료 모델, 접촉·동역학 등 물리적 의미의 선택
+- 합리적인 두 acceptance 기준이 동일 evidence를 pass와 fail로 나누고 그 선택이 제품
+  acceptance 의미나 공개 정확도 약속을 바꾸는 경우
+- authoritative input/output schema나 영속 public contract의 비호환 변경
+- authoritative requirement와 reference evidence가 충돌하고 기술 evidence로 우선순위를
+  결정할 수 없는 경우
+- 외부 solver 실행에 필요한 라이선스·자격증명·비공개 자료
+- 보안·신뢰 경계 또는 credential 처리의 중대한 변경, 해결되지 않은 보안·법률·라이선스
+  위험의 수용
+- destructive Git 작업, 외부 게시, push, tag, deploy, package 또는 release
+
+질문은 결정 가능한 대안, downstream 영향과 권고안을 하나로 묶는다. 단순 진행 확인,
+일반 문서 승인, 계획 승인 또는 agent 간 handoff 승인을 반복해서 요청하지 않는다.
+
+## 8. 실패 분류와 유한 correction
+
+실패 분류는 최소한 다음 값을 정규화해 사용한다.
+
+```text
+configure | compile | link | test | reference-comparison | harness |
+environment | upstream-contract | physics | evidence
+```
+
+Coordinator는 다음 요소로 retry signature를 만든다.
+
+```text
+retry_key = feature_id | failing_gate | normalized_failure_classification | contract_revision
+```
+
+동일 `retry_key`에 대한 Correction loop는 한 번만 허용한다.
+
+1. Implementation Agent가 실패를 분류하고 명백한 implementation-owned defect를 최소 수정·재검증한다.
+2. 반복되거나 원인이 불명확하면 Coordinator가 해당 key의 correction 사용 이력을 확인한다.
+3. 사용 이력이 없을 때만 Correction Agent를 한 번 dispatch한다.
+4. Correction Agent는 `retry`로 Implementation rerun을 요청하고 Coordinator가 rerun을 dispatch한다.
+5. 같은 key가 다시 실패하면 두 번째 correction을 금지한다. 계약 문제는 `return-upstream`,
+   환경 문제는 `blocked-environment`, 실제 critical choice만 `needs-user-decision`으로 전환한다.
+
+문구만 바꾸거나 동일 계약 revision을 새 key로 가장하면 안 된다. Upstream 계약이 승인된 방식으로
+변경된 경우에만 `contract_revision`을 올리고 새 signature를 만든다.
+
+## 9. Evidence gate
+
+Coordinator는 `pass` 전에 다음을 확인한다.
+
+- 요구되는 산출물이 존재하고 owner가 명시되어 있다.
+- 선행 artifact와 revision이 일치하며 stale evidence가 아니다.
+- 실행 증거에는 실제 명령, 종료 코드, 핵심 결과가 있다.
+- 수치 비교에는 quantity, unit, coordinate/component, matching rule과 적용 tolerance가 있다.
+- reference row의 missing, extra, duplicate와 nonfinite 값은 tolerance 판정 전에 검출된다.
+- 가정, 미지원 범위와 잔여 위험이 기록되어 있다.
+- specialist owner의 결론을 Coordinator나 downstream agent가 대신 만들지 않았다.
+- Feature 문서 목록과 기본·상세 문서 링크가 유효하고 필수 상세 근거까지 검토되었다.
+
+Reference input과 결과 artifact는 명시적으로 소유 agent가 아닌 한 read-only다. 저장된 외부
+reference 결과를 임의로 생성·보정하거나 통과하도록 수치를 변경해서는 안 된다.
+
+## 10. 언어와 기록
+
+- 기능 문서는 사용자가 다른 언어를 요청하지 않는 한 한국어 Markdown으로 작성한다.
+- Agent id, field name, outcome, failure classification, requirement id, path와 command는 English를 유지한다.
+- Requirement id 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
+- Placeholder artifact는 만들지 않는다. Correction이 실제 발생할 때만 `corrections.md`를 만든다.
+- 모든 stage는 자신이 변경한 경로와 변경하지 않은 upstream contract를 명확히 기록한다.

docs/SOLVER_SKILL_DESIGN.md

@@ -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 부재 또는 미실행을 성공으로 간주하지 않는다.