add reference and remove docu
This commit is contained in:
KOKO\Mimi
-153
@@ -1,153 +0,0 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
이 문서는 구조해석 FEM solver framework의 현재 architecture decision을 한 곳에서 관리한다.
|
||||
모든 항목은 별도 표기가 없으면 `Accepted`다. 결정을 바꿀 때 기존 항목을 삭제하거나 의미를
|
||||
바꾸지 않고 새 ADR에서 `Supersedes` 관계를 기록한다.
|
||||
|
||||
## ADR-001: Solver core와 adapter의 계층 분리
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Semantic model, element/material, analysis와 results를 core에 두고 input,
|
||||
persistence, sparse/vendor backend는 adapter로 둔다. 의존성은 adapter에서 core로 향한다.
|
||||
- **근거**: Physics와 numerical contract가 file format 또는 vendor API 수명에 종속되는 것을
|
||||
방지한다.
|
||||
- **결과**: 작은 feature에서도 mapping layer가 필요하다. 대신 parser, storage와 backend를
|
||||
독립적으로 교체·시험할 수 있다.
|
||||
|
||||
## ADR-002: C++17과 MSVC x64를 초기 검증 baseline으로 사용
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Solver production code의 최소 언어 수준은 C++17이며 Windows baseline은 MSVC
|
||||
x64다. CMake/CTest 또는 명시된 Visual Studio solution은 `.harness/config.json`에서
|
||||
선택한다.
|
||||
- **근거**: 현재 Harness가 검증 가능한 현실적 baseline을 제공하면서 vendor extension을
|
||||
public contract로 만들지 않기 위함이다.
|
||||
- **결과**: 다른 compiler/platform 지원은 별도 evidence가 생기기 전까지 보장하지 않는다.
|
||||
Toolchain upgrade는 compatibility 및 numerical regression 검토가 필요하다.
|
||||
|
||||
## ADR-003: Feature contract와 TDD를 구현 선행 조건으로 사용
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Requirement, formulation, numerical/verification와 I/O contract가 준비된 뒤
|
||||
production 구현을 시작한다. 구현은 실패 test 관찰 후 최소 변경으로 통과시킨다.
|
||||
- **근거**: 수식이나 output meaning이 불명확한 상태에서 코드가 사실상의 계약이 되는 것을
|
||||
방지한다.
|
||||
- **결과**: 작은 변경에도 직접 test와 evidence가 필요하다. 명백한 상위 계약 결함은
|
||||
implementation에서 우회하지 않고 owner에게 반환한다.
|
||||
|
||||
## ADR-004: Abaqus는 공개 reference convention이며 solver identity가 아님
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: 공식 Abaqus 문서의 입력 의미, analysis procedure, output definition과 verification
|
||||
사례를 observable behavior 기준으로 사용한다. 선택된 `.inp` subset은 adapter contract로
|
||||
구현한다.
|
||||
- **근거**: 익숙하고 문서화된 CAE convention을 활용하면서 비공개 구현 복제나 과도한
|
||||
호환성 주장을 피한다.
|
||||
- **결과**: 지원 subset과 차이를 명시해야 한다. 내부 알고리즘 동등성, 전체 호환성과
|
||||
bitwise result 일치를 주장하지 않는다. 다른 interchange adapter도 core를 변경하지 않고
|
||||
추가할 수 있다.
|
||||
|
||||
## ADR-005: Stable typed identity를 배열 위치와 분리
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Source label, internal entity, DOF, equation과 result key를 서로 다른 identity로
|
||||
표현한다. 외부 result/reference 매칭은 row order 대신 semantic key를 사용한다.
|
||||
- **근거**: Renumbering, filtering, parallel processing과 storage ordering이 physical identity를
|
||||
훼손하지 않게 한다.
|
||||
- **결과**: Explicit mapping 비용이 생기지만 duplicate/missing/extra entity를 deterministic하게
|
||||
검출할 수 있다.
|
||||
|
||||
## ADR-006: Immutable model과 transactional analysis state
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: 검증된 model definition은 analysis 동안 immutable하다. Iteration의 trial state와
|
||||
마지막 converged committed state를 분리하고 성공한 increment만 commit한다.
|
||||
- **근거**: Nonlinear/material update 실패가 다음 retry와 published result를 오염시키지 않게
|
||||
한다.
|
||||
- **결과**: State copy, checkpoint 또는 rollback protocol이 필요하다. 성능 최적화는 동일한
|
||||
failure atomicity를 보존해야 한다.
|
||||
|
||||
## ADR-007: Local element kernel과 global assembly를 분리
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Element는 명시적 local ordering으로 residual/tangent와 recovery data를 반환한다.
|
||||
DOF numbering, sparsity, scatter, constraint와 global reduction은 별도 module이 소유한다.
|
||||
- **근거**: Element formulation을 작은 test로 검증하고 여러 assembly/backend에서 재사용하기
|
||||
위함이다.
|
||||
- **결과**: Evaluation context와 local contribution contract가 필요하다. Element가 global
|
||||
matrix나 source parser에 직접 접근하는 편의는 허용하지 않는다.
|
||||
|
||||
## ADR-008: Deterministic ordering과 reduction을 correctness로 취급
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Numbering, contribution ordering, floating-point reduction tree와 output ordering을
|
||||
명시적으로 관리한다. 병렬화는 동일 identity와 허용된 numerical envelope를 검증한다.
|
||||
- **근거**: 회귀 비교, 문제 재현과 물리 검토가 실행 scheduling에 좌우되지 않게 한다.
|
||||
- **결과**: 일부 빠른 비결정적 알고리즘을 사용할 수 없거나 별도 opt-in contract가 필요할
|
||||
수 있다.
|
||||
|
||||
## ADR-009: Structured diagnostic과 fail-closed semantic validation
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Input/model/formulation/assembly/solver/convergence/recovery/storage/environment 실패를
|
||||
stable category와 code로 반환한다. 지원하지 않는 의미는 기본적으로 오류다.
|
||||
- **근거**: Silent fallback이나 warning-only 처리가 잘못된 해석을 정상 결과처럼 보이게 하는
|
||||
위험이 크다.
|
||||
- **결과**: Parser와 adapter가 더 엄격할 수 있다. 결과에 영향이 없다고 명시된 construct만
|
||||
warning으로 낮출 수 있다.
|
||||
|
||||
## ADR-010: Backend-neutral results와 versioned persistence
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Physical result identity를 in-memory results model이 소유하고 CSV, HDF5 또는 다른
|
||||
저장 형식은 versioned adapter가 projection한다. Validated candidate만 atomic publish한다.
|
||||
- **근거**: 저장 layout 변경이 solver physics와 public quantity 의미를 바꾸지 않게 한다.
|
||||
- **결과**: Schema version, units, coordinates, location, step/frame와 provenance metadata가
|
||||
필요하다. 특정 저장 형식은 feature/project 설정으로 선택한다.
|
||||
|
||||
## ADR-011: 다중 방법 verification과 immutable reference artifact
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Unit/patch/analytical/manufactured/convergence/invariant/reference comparison 중
|
||||
feature에 적합한 둘 이상의 독립 방법을 사용한다. 승인된 reference input, expected result와
|
||||
tolerance는 implementation이 수정할 수 없다.
|
||||
- **근거**: 같은 가정을 공유하는 한 가지 비교만으로는 formulation, mapping과 implementation
|
||||
오류를 구분하기 어렵다.
|
||||
- **결과**: Evidence 준비 비용이 증가한다. Artifact가 없거나 상충하면 구현을 억지로 맞추지
|
||||
않고 numerical/reference owner에게 반환한다.
|
||||
|
||||
## ADR-012: Coordinator-owned workflow와 critical-only human gate
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Coordinator가 공통 handoff envelope를 검증하고 다음 owner와 state transition을
|
||||
결정한다. Agent는 승인 범위의 repository-local 작업을 자율 수행하며 제품 의미, 공개
|
||||
호환성, acceptance, authoritative artifact, 보안·법률 위험 수용 또는 외부 권한을 바꾸는
|
||||
결정만 사용자에게 요청한다.
|
||||
- **근거**: 모든 단계의 반복 승인 병목을 제거하면서 되돌리기 어렵거나 제품 정의를 바꾸는
|
||||
선택은 사람이 통제하게 한다.
|
||||
- **결과**: 상태 schema, evidence digest, retry signature와 허용 transition을 기계적으로
|
||||
검증해야 한다. 같은 signature의 correction은 한 번만 허용한다.
|
||||
|
||||
## ADR-013: Project configuration은 실행 가능한 신뢰 경계
|
||||
|
||||
- **상태**: Accepted
|
||||
- **결정**: Build preset, solution과 test command를 포함하는 `.harness/config.json`은 code와
|
||||
같은 review 대상이다. Harness는 repository-relative path와 구조화된 command만 허용하고
|
||||
unrelated working-tree content를 stage하지 않는다.
|
||||
- **근거**: `shell=False`만으로 executable 또는 preset의 side effect를 격리할 수 없기
|
||||
때문이다.
|
||||
- **결과**: 임의 PATH executable과 repository 밖 command는 거부한다. `danger-full-access`,
|
||||
remote push와 파괴 작업에는 명시적 권한 및 격리 조건이 필요하다.
|
||||
|
||||
## ADR 추가 기준
|
||||
|
||||
다음 변경은 새 ADR이 필요하다.
|
||||
|
||||
- Core dependency 방향 또는 public module 경계 변경
|
||||
- Identity, units, coordinates, state ownership 또는 result meaning 변경
|
||||
- Analysis lifecycle, constraint 방식 또는 convergence contract의 공통 정책 변경
|
||||
- 지원 toolchain/platform baseline 또는 persistence compatibility 변경
|
||||
- Agent 권한, human gate 또는 authoritative evidence precedence 변경
|
||||
|
||||
단순 구현 세부사항, 한 feature에만 적용되는 formulation과 되돌릴 수 있는 내부 refactoring은
|
||||
해당 feature 문서나 implementation plan에 기록한다.
|
||||
@@ -1,285 +0,0 @@
|
||||
# Structural FEM Solver Architecture
|
||||
|
||||
## 1. 범위와 현재 상태
|
||||
|
||||
이 문서는 범용 구조해석 FEM solver의 목표 C++ 아키텍처와 이를 개발하는 control plane을
|
||||
정의한다. 현재 repository에는 agent/skill, 문서와 Harness가 있으며 solver source와 build
|
||||
metadata는 아직 없다. 아래 `include/`와 `src/` 구조는 feature 구현 시 지켜야 할 목표
|
||||
경계이지 현재 구현 완료 목록이 아니다.
|
||||
|
||||
## 2. 아키텍처 원칙
|
||||
|
||||
- Physics와 numerical meaning을 file format 및 vendor backend보다 안쪽에 둔다.
|
||||
- Model definition, mutable analysis state와 recovered result를 별도 lifetime으로 관리한다.
|
||||
- Local element 계산과 global topology/assembly/solve 책임을 분리한다.
|
||||
- 모든 경계에서 identity, units, coordinates, ordering과 failure를 명시한다.
|
||||
- Candidate를 완전히 검증한 뒤 authoritative state로 commit한다.
|
||||
- 지원하지 않는 semantic input은 fail closed 처리한다.
|
||||
- 재현 가능한 ordering과 reduction을 correctness contract로 취급한다.
|
||||
- 확장점은 실제 두 번째 구현이 필요할 때 최소 interface로 도입한다.
|
||||
|
||||
## 3. Context 구조
|
||||
|
||||
```text
|
||||
Development control plane
|
||||
user -> Coordinator -> specialist agents -> evidence -> Harness/tests
|
||||
|
|
||||
v
|
||||
repository changes
|
||||
|
||||
Solver data plane
|
||||
input adapter -> semantic model -> analysis procedure -> results model
|
||||
| |
|
||||
v v
|
||||
element/material assembly/constraints
|
||||
\ /
|
||||
numerical backend
|
||||
|
|
||||
output adapters
|
||||
```
|
||||
|
||||
Control plane은 source와 evidence를 만들고 검증하지만 solver runtime API의 일부가 아니다.
|
||||
Solver data plane은 agent, prompt, phase 파일 또는 Harness에 의존하지 않는다.
|
||||
|
||||
## 4. 목표 디렉터리
|
||||
|
||||
```text
|
||||
include/fem/
|
||||
core/ public identity, units, diagnostics와 value types
|
||||
model/ immutable semantic model API
|
||||
element/ element formulation contracts
|
||||
material/ constitutive contracts
|
||||
analysis/ analysis procedure contracts
|
||||
results/ backend-neutral result identity와 query API
|
||||
|
||||
src/
|
||||
core/
|
||||
model/
|
||||
element/
|
||||
material/
|
||||
dof/
|
||||
assembly/
|
||||
constraints/
|
||||
analysis/
|
||||
numerics/
|
||||
results/
|
||||
io/
|
||||
abaqus/ 선택적으로 지원하는 Abaqus interchange subset adapter
|
||||
storage/ 선택된 result serialization adapter
|
||||
|
||||
tests/
|
||||
unit/
|
||||
integration/
|
||||
verification/
|
||||
harness/
|
||||
|
||||
reference/ 승인된 read-only model 및 expected-result artifact
|
||||
docs/features/ feature별 requirement부터 release까지의 evidence
|
||||
```
|
||||
|
||||
첫 feature는 필요한 경로만 추가한다. 빈 framework class나 미래용 계층을 미리 만들지 않는다.
|
||||
|
||||
## 5. 모듈 책임
|
||||
|
||||
| 모듈 | 소유 책임 | 소유하지 않는 책임 |
|
||||
| --- | --- | --- |
|
||||
| `core` | typed identity, units/coordinate metadata, status/diagnostic | mesh, solver, file syntax |
|
||||
| `model` | node/connectivity/set/load/constraint/step의 검증된 semantic definition | equation numbering, mutable state |
|
||||
| `element` | kinematics, quadrature, local residual/tangent, recovery | global matrix와 source parsing |
|
||||
| `material` | constitutive response, trial/commit/revert state | element interpolation과 analysis loop |
|
||||
| `dof` | active DOF와 deterministic equation numbering | constraint enforcement와 solve |
|
||||
| `assembly` | sparsity, scatter, stable local-to-global reduction | element physics와 linear solve |
|
||||
| `constraints` | prescribed/MPC 등 feature가 지원하는 equation policy | parser syntax와 result storage |
|
||||
| `analysis` | procedure lifecycle, iteration, convergence, state commit | concrete file adapter와 vendor API 노출 |
|
||||
| `numerics` | vector/matrix abstraction과 private backend adapter | physical entity 및 source label 의미 |
|
||||
| `results` | quantity/location/component/frame/provenance identity와 recovery records | storage file layout |
|
||||
| `io` | external syntax와 semantic model 간 mapping | solver physics 변경 |
|
||||
| `storage` | versioned serialization과 atomic publication | authoritative physical meaning 정의 |
|
||||
|
||||
## 6. 의존성 규칙
|
||||
|
||||
```text
|
||||
io adapters ------> model/core <------ output/storage adapters
|
||||
^
|
||||
|
|
||||
element/material --> analysis <-- constraints/assembly
|
||||
| |
|
||||
+------------> numerics
|
||||
|
||||
public API -> core/model/element/material/analysis/results abstractions only
|
||||
```
|
||||
|
||||
- Adapter가 core contract에 의존하며 core가 adapter에 의존하지 않는다.
|
||||
- `element`와 `material`은 서로의 concrete type을 소유하지 않는다. 명시적 evaluation
|
||||
context/response contract로 통신한다.
|
||||
- `analysis`는 backend-neutral numerical interface만 본다.
|
||||
- Vendor header, handle과 exception은 `src/numerics` 또는 `src/storage` 내부에서 끝난다.
|
||||
- `io`가 model object를 부분적으로 publish하지 않는다. Builder/candidate를 검증한 뒤
|
||||
immutable model을 생성한다.
|
||||
|
||||
CI에서는 public-header self-containment와 금지 dependency 검사를 추가할 수 있다. 그런
|
||||
검사가 아직 없으면 architecture review가 동일 경계를 확인한다.
|
||||
|
||||
## 7. 핵심 데이터 계약
|
||||
|
||||
### 7.1 Identity
|
||||
|
||||
다음 identity는 교환할 수 없다.
|
||||
|
||||
- `SourceLabel`: input/output에서 사용자가 보는 label
|
||||
- `EntityId`: 검증된 model 내부 identity
|
||||
- `DofId`: physical component가 포함된 자유도 identity
|
||||
- `EquationId`: 특정 analysis state의 active equation 번호
|
||||
- `ResultKey`: entity, quantity, location, component, step/frame와 coordinate metadata 조합
|
||||
|
||||
Dense array index를 source label로 암묵적으로 사용하지 않는다. 외부 artifact 매칭은 row
|
||||
순서가 아니라 명시적 identity를 사용한다.
|
||||
|
||||
### 7.2 Units와 coordinates
|
||||
|
||||
Solver는 입력 값의 일관 단위계를 임의로 추론하지 않는다. Feature contract가 필요한
|
||||
dimension을 정의하고 adapter가 단위 metadata를 보존하거나 명시적으로 변환한다. Vector,
|
||||
tensor, rotation과 result component는 local/global/material coordinate system과 ordering을
|
||||
기록한다.
|
||||
|
||||
### 7.3 Model, state, results
|
||||
|
||||
- `Model`: analysis 동안 변하지 않는 topology와 semantic definition
|
||||
- `AnalysisState`: DOF values, committed/trial material state, iteration/convergence metadata
|
||||
- `Results`: 성공적으로 publish된 step/frame별 physical output
|
||||
|
||||
Trial update 실패 시 committed state를 보존한다. 실패 frame은 정상 frame과 같은
|
||||
authoritative status로 노출하지 않는다.
|
||||
|
||||
## 8. 해석 생명주기
|
||||
|
||||
```text
|
||||
PARSE/BUILD
|
||||
-> SEMANTIC VALIDATION
|
||||
-> MODEL FREEZE
|
||||
-> PROCEDURE INITIALIZATION
|
||||
-> DOF/CONSTRAINT SETUP
|
||||
-> SPARSITY SETUP
|
||||
-> {ASSEMBLE -> SOLVE -> UPDATE -> CONVERGENCE CHECK}*
|
||||
-> COMMIT
|
||||
-> RECOVER
|
||||
-> PUBLISH RESULTS
|
||||
```
|
||||
|
||||
Linear procedure도 같은 owner 경계를 사용하며 반복 구간이 한 번일 수 있다. Nonlinear,
|
||||
dynamic, eigen과 contact 기능은 이 lifecycle 위에 필요한 state와 gate를 추가하지만 다른
|
||||
analysis family의 의미를 공통 API에 억지로 넣지 않는다.
|
||||
|
||||
Residual과 tangent의 부호, essential constraint 적용 시점, reaction recovery와 state
|
||||
commit 시점은 formulation/analysis contract에 포함한다.
|
||||
|
||||
## 9. Element 및 material kernel
|
||||
|
||||
Element evaluation input은 최소한 geometry, DOF/state view, material evaluation capability,
|
||||
step/iteration context와 requested outputs를 포함한다. Output은 local ordering이 명시된
|
||||
residual/tangent 및 recovery data다.
|
||||
|
||||
Element kernel은 다음을 수행하지 않는다.
|
||||
|
||||
- global equation 번호 생성
|
||||
- global sparse matrix에 직접 write
|
||||
- source file lookup
|
||||
- global convergence 판정
|
||||
- result storage write
|
||||
|
||||
Material update는 trial response를 반환하고 analysis owner가 전체 increment 성공 후 commit을
|
||||
요청한다. Numerical integration point와 state-variable ordering은 feature contract에
|
||||
versioned되어야 한다.
|
||||
|
||||
## 10. Assembly, constraints와 numerics
|
||||
|
||||
- Sparsity는 validated connectivity와 DOF policy에서 deterministic하게 생성한다.
|
||||
- Parallel worker는 소유가 정해진 buffer에만 기록하고 reduction 순서를 고정한다.
|
||||
- Constraint 방식은 elimination, transformation, penalty 등 선택된 feature contract에
|
||||
명시한다. 서로 다른 방식의 reaction 의미를 동일하다고 가정하지 않는다.
|
||||
- Numerical backend는 matrix/storage/solver capability를 제공하지만 physical model을 알지
|
||||
않는다.
|
||||
- Backend status는 structured solver diagnostic으로 변환하며 exception이나 error code를
|
||||
public API로 그대로 흘리지 않는다.
|
||||
|
||||
## 11. I/O와 Abaqus reference convention
|
||||
|
||||
Abaqus input/output의 공개 정의는 호환 feature를 설계할 때 우선 reference로 사용한다.
|
||||
Adapter는 지원 keyword/option, model data와 history data, default, set/instance scope,
|
||||
orientation, step과 output 위치를 명시적으로 mapping한다.
|
||||
|
||||
다음 원칙을 지킨다.
|
||||
|
||||
- 선택된 subset만 지원한다고 선언한다.
|
||||
- 결과에 영향을 줄 수 있는 unknown/unsupported semantic keyword는 오류다.
|
||||
- 무시해도 semantic 차이가 없다고 계약된 formatting 또는 metadata만 warning이 될 수 있다.
|
||||
- 공개 문서로 확인할 수 없는 내부 동작을 추측하지 않는다.
|
||||
- Adapter의 interchange 호환성과 solver formulation 검증을 별개의 evidence로 관리한다.
|
||||
|
||||
다른 입력 형식도 동일한 semantic model builder를 사용한다.
|
||||
|
||||
기본 공개 reference set은 다음과 같다. Feature evidence에는 실제 사용한 product version과
|
||||
세부 page를 고정해 기록한다.
|
||||
|
||||
- [Input file model/history organization](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-ov.htm)
|
||||
- [Element selection and formulation overview](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-analysistype.htm)
|
||||
- [Nonlinear equation solution controls](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEANLRefMap/simaanl-c-nonlineareqns.htm)
|
||||
- [Output concepts and identifiers](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEOUTRefMap/simaout-c-ov.htm)
|
||||
- [Verification Guide](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEVERRefMap/simaver-c-ov.htm)
|
||||
|
||||
이 목록은 출발점이지 모든 feature의 충분한 근거가 아니다. Governing theory와 feature별
|
||||
공식 문서를 함께 사용하고, 문서 version 간 차이는 contract에 명시한다.
|
||||
|
||||
## 12. 결과와 persistence
|
||||
|
||||
Results model은 저장 형식과 독립적이며 다음을 식별한다.
|
||||
|
||||
- analysis/step/frame와 success status
|
||||
- entity와 source identity
|
||||
- quantity, location, component와 coordinate system
|
||||
- units/dimension와 precision
|
||||
- formulation, mesh와 solver provenance
|
||||
|
||||
Storage adapter는 schema version을 기록하고 임시 candidate에 쓴 뒤 validation 성공 시
|
||||
atomic publish한다. CSV, HDF5 또는 다른 형식은 선택된 project/feature contract이며 core
|
||||
기본값이 아니다.
|
||||
|
||||
## 13. 오류 모델
|
||||
|
||||
오류는 적어도 다음 category를 구분한다.
|
||||
|
||||
`input`, `model`, `formulation`, `assembly`, `constraint`, `linear-solver`, `convergence`,
|
||||
`recovery`, `storage`, `environment`, `internal`
|
||||
|
||||
Diagnostic에는 category, stable code, message, 관련 entity/source location과 원인 chain을
|
||||
포함할 수 있다. 예상 가능한 사용자/model 오류는 process crash나 assertion으로 처리하지
|
||||
않는다. Assertion은 내부 invariant 위반에 사용한다.
|
||||
|
||||
## 14. Determinism과 병렬성
|
||||
|
||||
- Entity와 equation ordering은 stable input identity와 명시적 policy에서 결정한다.
|
||||
- Hash iteration order를 authoritative output order로 사용하지 않는다.
|
||||
- Floating-point reduction tree를 고정하거나 비결정성 범위를 계약·검증한다.
|
||||
- 병렬 최적화는 serial reference test와 동일한 identity 및 허용된 numerical envelope를
|
||||
만족해야 한다.
|
||||
- Randomized test는 seed와 재현 정보를 기록한다.
|
||||
|
||||
## 15. 개발 control plane
|
||||
|
||||
Coordinator와 specialist agent는 `docs/SOLVER_AGENT_DESIGN.md`의 state machine을 따른다.
|
||||
Skill은 역할별 절차를 제공하고 Harness는 계획된 repository-local 변경의 TDD와 build/test를
|
||||
강제한다.
|
||||
|
||||
Control plane의 안전 경계는 다음과 같다.
|
||||
|
||||
- Agent 보고서와 runtime output을 product result로 취급하지 않는다.
|
||||
- Hook은 방어 계층이지 완전한 sandbox가 아니다.
|
||||
- Project config와 build preset은 실행 가능한 신뢰 경계다.
|
||||
- Harness는 관련 없는 working-tree 변경을 stage/commit하지 않는다.
|
||||
- External solver와 원격 repository 변경은 별도 권한이 필요하다.
|
||||
|
||||
## 16. Architecture 변경
|
||||
|
||||
Public dependency 방향, identity, state ownership, result schema 의미 또는 analysis lifecycle을
|
||||
바꾸는 변경은 `docs/ADR.md`에 새 decision을 추가한다. 기존 ADR을 조용히 다시 쓰지 않고
|
||||
superseding ADR로 이력을 남긴다.
|
||||
@@ -1,192 +0,0 @@
|
||||
# Structural FEM Solver C++ Coding Style
|
||||
|
||||
## 목적과 우선순위
|
||||
|
||||
이 문서는 production 및 test C++의 project-local 규칙이다. [Google C++ Style
|
||||
Guide](https://google.github.io/styleguide/cppguide.html)를 일반 baseline으로 사용하되 다음
|
||||
순서가 우선한다.
|
||||
|
||||
1. 승인된 feature requirements, formulation, numerical/verification와 I/O contract
|
||||
2. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`
|
||||
3. 이 문서
|
||||
4. Google C++ Style Guide
|
||||
5. 수정 대상 module의 기존 local style
|
||||
|
||||
요청 범위 밖 파일을 style-only 이유로 수정하지 않는다. 새 코드는 즉시 준수하고 기존
|
||||
코드는 승인된 변경 slice 안에서만 점진적으로 정리한다.
|
||||
|
||||
## Language와 toolchain
|
||||
|
||||
- 최소 language level은 C++17이다.
|
||||
- Windows validation baseline은 MSVC x64다.
|
||||
- Compiler extension과 운영체제 전용 type을 public API에 노출하지 않는다.
|
||||
- Build generator, preset, configuration과 test command는 `.harness/config.json`을 우선한다.
|
||||
- Standard library, RAII와 value semantics를 manual lifetime management보다 우선한다.
|
||||
- Vendor linear algebra, sparse, persistence와 OS header는 private adapter 내부에 둔다.
|
||||
|
||||
## 파일과 header
|
||||
|
||||
- File 이름은 소문자 `snake_case`를 사용한다.
|
||||
- Source는 `.cpp`, header는 `.h`를 사용한다. 이미 존재하는 다른 extension은 별도 migration
|
||||
없이 이름만 바꾸지 않는다.
|
||||
- Header는 self-contained이며 consumer의 transitive include에 의존하지 않는다.
|
||||
- Full repository path 기반 include guard를 사용한다.
|
||||
|
||||
```cpp
|
||||
#ifndef FEM_CORE_VECTOR3_H_
|
||||
#define FEM_CORE_VECTOR3_H_
|
||||
|
||||
namespace fem {
|
||||
|
||||
class Vector3 {};
|
||||
|
||||
} // namespace fem
|
||||
|
||||
#endif // FEM_CORE_VECTOR3_H_
|
||||
```
|
||||
|
||||
Include group은 대응 header, C system, C++ standard library, third party, project header
|
||||
순서다. 각 group 사이에 빈 줄을 두고 직접 사용하는 declaration의 header를 include한다.
|
||||
|
||||
## 이름 규칙
|
||||
|
||||
| 대상 | 규칙 | 예 |
|
||||
| --- | --- | --- |
|
||||
| class, struct, enum, alias | `PascalCase` | `ElementProperty` |
|
||||
| function, method, accessor | `PascalCase` | `ComputeResidual()` |
|
||||
| local variable, parameter | `snake_case` | `element_id` |
|
||||
| class data member | `snake_case_` | `youngs_modulus_` |
|
||||
| struct data member | `snake_case` | `source_label` |
|
||||
| constant | `kPascalCase` | `kNodeCount` |
|
||||
| enumerator | `kPascalCase` | `FailureKind::kModel` |
|
||||
| namespace | `snake_case` | `fem::numerics_internal` |
|
||||
| macro | `UPPER_SNAKE_CASE` | `FEM_CORE_VECTOR3_H_` |
|
||||
|
||||
Root namespace는 실제 project bootstrap에서 한 번 선택한다. 위 `fem`은 예시이며 여러
|
||||
feature가 서로 다른 root namespace를 만들지 않는다.
|
||||
|
||||
이름은 physical/numerical 의미를 드러내야 한다. 넓은 scope의 `data`, `value`, `manager`,
|
||||
`handler`를 피하고 source label, entity ID, DOF ID와 equation ID를 이름에서 구분한다.
|
||||
|
||||
## Formatting
|
||||
|
||||
- `.clang-format`은 Google 기반, space 2개와 최대 100 columns를 기본으로 한다.
|
||||
- Tab을 사용하지 않는다.
|
||||
- Declaration/control statement와 같은 줄에 opening brace를 둔다.
|
||||
- Namespace body는 들여쓰지 않고 closing namespace comment를 작성한다.
|
||||
- 한 statement에 한 declaration만 둔다.
|
||||
- Variable은 가능한 가장 좁은 scope에서 선언과 동시에 초기화한다.
|
||||
- 의미가 허용하면 `const`, `constexpr`, `explicit`, `override`, `noexcept`와 `[[nodiscard]]`를
|
||||
사용한다. 장식 목적으로 contract를 과장하지 않는다.
|
||||
- Formatting-only 변경과 behavior 변경을 불필요하게 섞지 않는다.
|
||||
|
||||
## API와 ownership
|
||||
|
||||
- Public interface는 현재 필요한 최소 capability만 제공한다.
|
||||
- Class는 하나의 명확한 responsibility와 invariant를 가진다.
|
||||
- Invariant, encapsulation, lifetime 또는 behavior가 없으면 data-only `struct`를 사용할 수 있다.
|
||||
- 단독 ownership은 `std::unique_ptr` 또는 value로 표현한다. 실제 shared lifetime이 없으면
|
||||
`std::shared_ptr`를 사용하지 않는다.
|
||||
- Non-owning pointer/reference/span의 lifetime과 nullability를 API contract에 기록한다.
|
||||
- Polymorphic base에는 public virtual destructor가 있어야 한다.
|
||||
- Downcast와 type switch를 주요 확장 mechanism으로 사용하지 않는다.
|
||||
- 단일 사용을 위해 abstract factory, registry 또는 future option을 만들지 않는다.
|
||||
- Public header는 implementation/vendor dependency 방향을 역전하지 않는다.
|
||||
|
||||
## FEM module 규칙
|
||||
|
||||
- `model`은 validated immutable semantic definition을 소유한다.
|
||||
- `element`는 local residual/tangent와 recovery를 소유하며 global matrix를 직접 수정하지 않는다.
|
||||
- `material`은 constitutive trial/commit/revert contract를 소유한다.
|
||||
- `dof`는 active DOF와 equation numbering을 소유한다. Node가 equation ID를 영구 저장하지
|
||||
않는다.
|
||||
- `assembly`는 sparsity, scatter와 deterministic reduction을 소유한다.
|
||||
- `constraints`는 equation policy를 소유한다.
|
||||
- `analysis`는 procedure lifecycle, convergence와 state commit을 소유한다.
|
||||
- `results`는 physical result identity를 소유하고 persistence layout을 알지 않는다.
|
||||
- `io`와 `storage`는 external representation을 core contract에 mapping한다.
|
||||
- `numerics`는 physical entity를 알지 않는 backend-neutral operation을 제공한다.
|
||||
|
||||
비슷해 보이는 수식을 공통화하기 전에 units, sign, coordinates, result location, state lifetime와
|
||||
tolerance가 같은지 확인한다. 한 번만 사용하는 logic을 future flexibility를 위해 framework로
|
||||
만들지 않는다.
|
||||
|
||||
## 수치 코드
|
||||
|
||||
- DOF/component/local-node ordering은 type, constant 또는 contract로 명시한다.
|
||||
- Shape derivative, Jacobian, quadrature weight와 coordinate transform의 convention을 수식과
|
||||
test에서 동일하게 유지한다.
|
||||
- Residual과 tangent의 부호 및 linearization point를 주석/contract에 기록한다.
|
||||
- Parallel worker는 owner가 정해진 output만 수정하고 floating-point reduction 순서를
|
||||
의도적으로 결정한다.
|
||||
- 임의 clamp, `max(1, ...)`, missing-row ignore와 silent fallback을 추가하지 않는다.
|
||||
- `double` 값의 equality를 일반적인 engineering quantity에 직접 사용하지 않고
|
||||
`docs/TOLERANCE.md`의 목적별 metric을 사용한다.
|
||||
- 성능 변경 전 benchmark와 correctness baseline을 기록한다. Expression order를 바꾸는
|
||||
optimization은 numerical regression을 다시 검증한다.
|
||||
|
||||
## Error와 failure atomicity
|
||||
|
||||
- 예상 가능한 실패는 project의 `Status`/`Result<T>` 계약으로 반환한다.
|
||||
- Backend exception과 raw error code가 public solver boundary를 통과하지 않게 한다.
|
||||
- Unsupported type/property/material/procedure 조합은 structured diagnostic으로 fail closed한다.
|
||||
- Candidate model/state/result를 완성해 검증한 뒤 authoritative owner에 commit한다.
|
||||
- Partial failure가 기존 committed state 또는 정상 result artifact를 덮어쓰지 않게 한다.
|
||||
- Assertion은 사용자 입력 오류가 아니라 내부 invariant 위반에 사용한다.
|
||||
|
||||
## Documentation
|
||||
|
||||
Public/protected production declaration은 필요한 경우 다음을 영어 Doxygen로 기록한다.
|
||||
|
||||
- purpose와 physical/numerical meaning
|
||||
- units, coordinates, ordering과 valid range
|
||||
- ownership, lifetime, precondition과 failure
|
||||
- deterministic behavior 또는 backend limitation
|
||||
- sign, trial/committed state와 destructive side effect 주의
|
||||
|
||||
```cpp
|
||||
/// @brief Computes an element contribution in the declared local DOF order.
|
||||
/// @return A finite residual and consistent tangent, or a structured failure.
|
||||
/// @note This function does not modify the global system or committed state.
|
||||
virtual Result<ElementContribution> Evaluate(
|
||||
const ElementContext& context) const = 0;
|
||||
```
|
||||
|
||||
코드가 말하는 내용을 번역하는 comment는 쓰지 않는다. 비자명한 formulation, operation order,
|
||||
ownership 또는 선택 이유를 설명한다. Test helper에는 형식적인 Doxygen를 요구하지 않는다.
|
||||
|
||||
## Test와 변경 관리
|
||||
|
||||
- Production C++ 변경은 관련 test 변경과 같은 patch에 포함한다.
|
||||
- `RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY`를 따른다.
|
||||
- Test는 정상값뿐 아니라 invalid combination, identity/order, state rollback, determinism과
|
||||
error category를 검증한다.
|
||||
- Numerical feature는 직접 kernel test와 독립 system/benchmark evidence를 모두 가진다.
|
||||
- Reference artifact나 tolerance를 implementation 결과에 맞춰 수정하지 않는다.
|
||||
- 새 warning, flaky test 또는 검증되지 않은 platform 성공 주장을 추가하지 않는다.
|
||||
- Commit을 요청받으면 review 가능한 module slice와 Conventional Commits 형식을 사용한다.
|
||||
|
||||
## Tooling
|
||||
|
||||
Repository 설정과 존재하는 target에만 적용한다.
|
||||
|
||||
```powershell
|
||||
clang-format --dry-run --Werror <changed-cpp-and-header-files>
|
||||
clang-tidy <changed-cpp-files> -- -std=c++17
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Tool, build metadata 또는 target이 없으면 검사를 성공으로 표시하지 말고 `미실행`과 이유를
|
||||
보고한다. Generated documentation, build directory, cache와 runtime output은 source control에
|
||||
넣지 않는다.
|
||||
|
||||
## Implementation checklist
|
||||
|
||||
- 승인된 feature contract와 직접 관련된 파일만 변경한다.
|
||||
- Public dependency 방향과 owner가 architecture와 일치한다.
|
||||
- 실패 test를 구현 전에 관찰했다.
|
||||
- Units, coordinates, identity와 local/global ordering이 드러난다.
|
||||
- Trial/committed state와 failure atomicity가 보존된다.
|
||||
- Focused test와 가능한 full build/test를 실제로 실행했다.
|
||||
- 미실행 검사, warning과 residual risk를 evidence에 기록했다.
|
||||
@@ -1,245 +0,0 @@
|
||||
# Harness Operations Guide
|
||||
|
||||
## 1. 역할과 현재 상태
|
||||
|
||||
Harness는 agent가 작성한 implementation Step을 독립 Codex session에서 실행하고, C/C++
|
||||
변경의 TDD guard, configured MSVC build/test, 상태와 local Git commit을 관리한다.
|
||||
|
||||
현재 repository에는 solver C++ source와 build metadata가 없다. 따라서 repository 자체에서는
|
||||
Python Harness regression suite를 검증하며, C++ build 성공을 주장하지 않는다. Solver feature가
|
||||
CMake 또는 Visual Studio metadata를 추가하면 Stop hook이 해당 project를 검증한다.
|
||||
|
||||
## 2. 요구 환경
|
||||
|
||||
- Windows와 Python 3.11 이상
|
||||
- Git과 Codex CLI
|
||||
- Harness test 실행용 `uv`
|
||||
- C++ project를 검증할 때 Visual Studio Desktop development with C++, MSBuild, CMake/CTest
|
||||
|
||||
실제 toolchain, generator, configuration과 test command는 `.harness/config.json` 및 project
|
||||
build metadata가 source of truth다.
|
||||
|
||||
## 3. 설정
|
||||
|
||||
설정이 없으면 Harness는 자동 감지를 사용한다. Override가 필요할 때만 tracked example을
|
||||
machine-local 설정으로 복사한다.
|
||||
|
||||
```powershell
|
||||
Copy-Item .harness/config.example.json .harness/config.json
|
||||
```
|
||||
|
||||
`.harness/config.json`은 ignore되며 code와 같은 실행 가능한 신뢰 경계다. Preset과 test
|
||||
executable은 arbitrary child process를 실행할 수 있으므로 review 없이 외부에서 받은 설정을
|
||||
사용하지 않는다.
|
||||
|
||||
지원하는 `projectType`은 `auto`, `cmake`, `msbuild`다. Unknown field, absolute/escaping path와
|
||||
불완전한 preset은 거부된다. TDD pattern은 directory separator가 없는 safe basename이어야 하며
|
||||
format field로 `{stem}`만 사용할 수 있다.
|
||||
|
||||
### CMake
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"projectType": "cmake",
|
||||
"cmake": {
|
||||
"sourceDir": ".",
|
||||
"binaryDir": ".harness/build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`binaryDir`은 non-preset plan에서도 사용할 수 있다. Preset을 사용하면 `configurePreset`,
|
||||
`buildPreset`, `testPreset`, `binaryDir`를 모두 지정한다. 자동 감지에서도 명시된
|
||||
`cmake.sourceDir`을 먼저 검사한다.
|
||||
|
||||
Preset이 없을 때의 기본 계획은 다음 형태다.
|
||||
|
||||
```powershell
|
||||
cmake -S <sourceDir> -B <binaryDir> -A x64
|
||||
cmake --build <binaryDir> --config Debug
|
||||
ctest --test-dir <binaryDir> -C Debug --show-only=json-v1
|
||||
ctest --test-dir <binaryDir> -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Harness는 compiler metadata가 MSVC인지, CTest가 한 개 이상의 test를 발견했는지도 확인한다.
|
||||
|
||||
### Visual Studio/MSBuild
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"projectType": "msbuild",
|
||||
"msbuild": {
|
||||
"solution": "Solver.sln",
|
||||
"configuration": "Debug",
|
||||
"platform": "x64",
|
||||
"testCommand": ["build/tests/Debug/SolverTests.exe"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`testCommand`는 필수이며 첫 항목은 repository-relative executable path여야 한다. Bare PATH
|
||||
program, absolute path와 repository escape는 허용되지 않는다. 인수는 배열의 후속 항목으로
|
||||
전달된다.
|
||||
|
||||
### TDD path mapping
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"tdd": {
|
||||
"testRoots": ["tests", "integration-tests"],
|
||||
"testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
|
||||
"exclude": ["generated/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Project exclude는 Harness의 build/vendor/generated 기본 exclude에 추가된다. Production C/C++
|
||||
파일을 편집하려면 mapping되는 test 파일이 먼저 존재해야 한다.
|
||||
|
||||
## 4. 계획과 실행
|
||||
|
||||
Coordinator가 승인된 feature bundle로 planning/execution을 dispatch하면 routine local 작업을
|
||||
위해 별도 사용자 승인을 반복하지 않는다. Planning Agent는 `.agents/skills/harness/SKILL.md`에
|
||||
따라 `phases/` index와 self-contained Step을 만든다.
|
||||
|
||||
Executor 시작 전 worktree는 선택한 phase의 선언된 control file 밖에서 깨끗해야 한다. 허용되는
|
||||
control file은 top/phase index, phase index에 선언된 `stepN.md`와 해당 local raw output뿐이다.
|
||||
|
||||
```powershell
|
||||
git status --short
|
||||
python scripts/execute.py <phase-name>
|
||||
```
|
||||
|
||||
Executor는 다음을 수행한다.
|
||||
|
||||
1. Safe phase name, repository/phase containment, top-level index, phase metadata, contiguous Step와
|
||||
status order 검증
|
||||
2. Implementation profile, exact Git top-level, sandbox 권한과 strict worktree preflight
|
||||
3. `feat-<phase>` branch checkout/create
|
||||
4. Implementation Agent 역할, project guardrail, prior summary와 current Step 주입
|
||||
5. Current Step의 Codex session 실행과 최대 2회 transport attempt
|
||||
6. Exit code와 Step payload 검증
|
||||
7. Implementation path와 phase metadata의 path-scoped local commit
|
||||
8. 모든 Step 완료 시 phase closure
|
||||
|
||||
일반 implementation failure는 Executor가 반복 수정하지 않는다. Step을 `error`로 기록하고
|
||||
Coordinator가 normalized `retry_key`와 correction budget으로 route한다.
|
||||
|
||||
## 5. Sandbox와 외부 변경
|
||||
|
||||
기본 sandbox는 `workspace-write`다. Windows native sandbox가 실제 compiler process를 막는
|
||||
것이 재현된 경우에만 사용자가 해당 실행을 명시 승인하고 clean linked worktree에서 다음 두
|
||||
조건을 함께 제공한다.
|
||||
|
||||
```powershell
|
||||
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
|
||||
python scripts/execute.py <phase-name> --approve-danger-full-access
|
||||
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
|
||||
```
|
||||
|
||||
Primary worktree, dirty worktree, 환경 변수만 설정한 실행은 거부된다. `danger-full-access`는
|
||||
hook을 끄지 않지만 hook이 완전한 sandbox라는 의미도 아니다.
|
||||
|
||||
원격 push는 별도 critical action이다. 사용자가 정확한 branch push를 승인한 경우에만
|
||||
실행한다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase-name> --push
|
||||
```
|
||||
|
||||
Executor는 force push, history rewrite, tag, publish 또는 deploy를 수행하지 않는다.
|
||||
|
||||
## 6. Hook 동작
|
||||
|
||||
`.codex/hooks.json`은 [Codex Hooks contract](https://learn.chatgpt.com/docs/hooks)에 따라
|
||||
PreToolUse와 Stop hook을 등록한다. Hook은 자동 실행하며 검증 대체를 위해 수동 호출하지
|
||||
않는다.
|
||||
|
||||
### PreToolUse
|
||||
|
||||
- 위험한 Git/delete/database command pattern을 exit code 2로 차단한다.
|
||||
- Implementation session의 commit, push, branch/switch, tag, merge/rebase와 history 변경 Git
|
||||
command를 차단한다. 이 동작은 Executor 또는 별도 승인된 외부 작업만 소유한다.
|
||||
- 공식 `apply_patch` payload의 `tool_input.command`에서 patch path를 추출한다.
|
||||
- C/C++ production path에 대응 test가 없으면 편집을 차단한다.
|
||||
- Malformed/unknown edit payload는 fail closed한다.
|
||||
|
||||
Test path 존재 검사는 실제 RED, assertion 품질 또는 coverage를 증명하지 않는다.
|
||||
|
||||
### Stop
|
||||
|
||||
- Payload의 `cwd`에서 Git root를 찾고 재진입을 방지한다.
|
||||
- Config/discovery/toolchain/adapter plan을 전체 deadline 안에서 실행한다.
|
||||
- 실패 시 current Codex hook contract의 `{"decision":"block","reason":"..."}`을 반환해
|
||||
같은 session이 수정하게 한다.
|
||||
- `stop_hook_active` 재진입은 즉시 허용한다.
|
||||
- Config argument의 control character를 거부하고 예상하지 못한 일반 예외도 block response로
|
||||
변환한다.
|
||||
- C/C++ source와 build metadata가 모두 없으면 검증 target 없음으로 정상 종료한다.
|
||||
- C/C++ source만 있고 build metadata가 없으면 orphan project로 차단한다.
|
||||
|
||||
## 7. Git과 runtime artifact
|
||||
|
||||
Preflight 이후 생성된 implementation path만 feature commit에 stage한다. 각 commit 직전에
|
||||
working tree는 보존한 채 index를 초기화한 다음 대상 path만 다시 stage하므로 agent가 미리 stage한
|
||||
metadata가 feature commit에 섞이지 않는다. Selected phase index, Step과 timestamps는 별도
|
||||
metadata commit에 stage한다. 관련 없는 pre-existing worktree 변경이나 phase 안의 미선언 파일이
|
||||
있으면 branch checkout 전에 실행을 거부한다.
|
||||
|
||||
각 Codex attempt 전후에는 symbolic branch와 HEAD도 비교한다. Session이 자체 commit, checkout
|
||||
또는 branch 변경으로 hook을 우회하면 결과를 신뢰하지 않고 current Step을 error로 고정한다.
|
||||
|
||||
Raw Codex `stdout`/`stderr`는 다음 local diagnostic file에 저장하지만 source control에는
|
||||
포함하지 않는다.
|
||||
|
||||
```text
|
||||
phases/<phase>/step<N>-output.json
|
||||
```
|
||||
|
||||
`.gitignore`는 위 파일, `.harness/config.json`, build output와 Python cache를 제외한다. Raw
|
||||
output은 credential을 포함할 수 있으므로 공유하거나 artifact로 게시하기 전에 검토한다.
|
||||
Control file은 non-link regular file로 읽고 phase/root containment를 매번 확인한다. Index,
|
||||
instruction 복구와 raw output write는 같은 directory의 임시 파일을 `os.replace`하는 atomic
|
||||
write를 사용해 symlink·hardlink target을 따라가 덮어쓰지 않는다.
|
||||
|
||||
## 8. 상태와 복구
|
||||
|
||||
| Step status | 필수 payload | 다음 처리 |
|
||||
| --- | --- | --- |
|
||||
| `pending` | 없음 | Executor가 선택 가능 |
|
||||
| `completed` | `summary` | timestamp와 commits 후 다음 Step |
|
||||
| `error` | `error_message` | Coordinator classification 전 중단 |
|
||||
| `blocked` | `blocked_reason` | 환경/권한/critical decision 해결 전 중단 |
|
||||
|
||||
Nonzero Codex exit는 Step이 `completed`를 썼더라도 신뢰하지 않는다. 두 transport attempt가
|
||||
실패하면 `error`와 `failed_at`을 기록한다. 재개는 Coordinator가 owner와 evidence를 확인한 뒤
|
||||
current Step을 `pending`으로 돌리는 방식으로 수행한다. Executor는 stale outcome timestamp를
|
||||
정리한다.
|
||||
|
||||
Codex session 전후로 top-level index와 모든 `stepN.md`를 byte 비교하고 phase index의 current
|
||||
Step outcome 외 변경을 거부한다. Future Step, instruction 또는 control metadata가 바뀌면 snapshot을
|
||||
복원하고 current Step을 trusted `error`로 기록하므로 다음 실행에서 조작된 완료 상태를 수락하지
|
||||
않는다.
|
||||
|
||||
## 9. Harness 자체 검증
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
python -B scripts/execute.py --help
|
||||
```
|
||||
|
||||
실제 Executor 기능 시험은 현재 repository에서 직접 실행하지 않는다. Branch/commit/Codex를
|
||||
변경하기 때문이다. Regression suite가 temporary Git repository와 hook subprocess를 사용해
|
||||
state, Git, payload와 failure behavior를 검증한다.
|
||||
|
||||
## 10. 한계
|
||||
|
||||
- `shell=False`와 repository-relative executable은 shell injection을 줄이지만 configured
|
||||
executable/preset의 side effect를 격리하지 않는다.
|
||||
- PreToolUse는 shell redirection 등 모든 파일 쓰기를 완전하게 해석하지 않는다.
|
||||
- Stop pass는 configured target의 build/test 결과이며 formulation과 physics correctness를
|
||||
대신하지 않는다.
|
||||
- External solver reference execution과 reference artifact 생성은 Harness 기본 권한 밖이다.
|
||||
@@ -1,285 +0,0 @@
|
||||
# Harness Execution Workflow
|
||||
|
||||
## 1. 목적
|
||||
|
||||
Harness는 승인된 구조 FEM feature contract를 작은 test-first Step으로 실행하고, 독립 Codex
|
||||
session, hook validation, 상태와 local Git commit을 deterministic하게 연결한다. 제품 workflow
|
||||
상태는 Coordinator가 소유하고, Executor는 선택된 implementation phase의 기계적 실행만
|
||||
소유한다.
|
||||
|
||||
## 2. 전체 흐름
|
||||
|
||||
```text
|
||||
approved feature bundle
|
||||
-> Coordinator dispatches Implementation Planning
|
||||
-> Planning Agent materializes phase/index/step files
|
||||
-> Coordinator checks plan evidence and dispatches local execution
|
||||
-> Executor preflight and feature branch
|
||||
-> current Step in an independent Codex session
|
||||
-> PreToolUse guard before commands/edits
|
||||
-> RED -> minimal GREEN -> focused/full VERIFY
|
||||
-> Stop hook configured build/test before response completion
|
||||
-> Executor validates exit + Step payload
|
||||
-> completed: path-scoped commits, next Step
|
||||
-> error: stop and return evidence to Coordinator
|
||||
-> blocked: stop until environment/user authority changes
|
||||
-> all completed: phase closure
|
||||
-> Coordinator dispatches physics evaluation
|
||||
```
|
||||
|
||||
승인된 scope 안의 planning materialization과 기본 local execution에는 stage마다 사용자 확인을
|
||||
반복하지 않는다. Physics/scope/public compatibility/product acceptance, authoritative artifact,
|
||||
external authority 또는 destructive/remote action만 별도 사용자 결정이다.
|
||||
|
||||
## 3. 책임 경계
|
||||
|
||||
| Component | Owns | Does not own |
|
||||
| --- | --- | --- |
|
||||
| Coordinator | workflow transition, contract revision, `retry_key`, correction budget | Step execution과 Git mechanics |
|
||||
| Planning Agent | implementation plan과 assigned phase files | source 구현과 Step 선택 |
|
||||
| Executor | preflight, branch, first pending Step, transport attempts, timestamps, local commits | physics/contract 판단과 correction 분류 |
|
||||
| Implementation Agent | current Step의 code/test/report와 result payload | 다른 Step, upstream contract와 workflow transition |
|
||||
| PreToolUse | dangerous-pattern 및 C++ test-path guard | 실제 RED와 correctness 증명 |
|
||||
| Stop | configured project의 build/test gate | numerical/physics/release 판정 |
|
||||
|
||||
## 4. Phase 계약
|
||||
|
||||
Top-level `phases/index.json`은 phase를 정확히 한 번 식별한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": [
|
||||
{"dir": "linear-solid", "status": "pending"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`phases/linear-solid/index.json`은 directory와 같은 `phase`, non-empty project와 0부터 연속인
|
||||
Step을 가진다.
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "Structural FEM Solver",
|
||||
"phase": "linear-solid",
|
||||
"steps": [
|
||||
{"step": 0, "name": "element-kernel", "status": "pending"},
|
||||
{"step": 1, "name": "global-assembly", "status": "pending"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
허용 status는 `pending`, `completed`, `error`, `blocked`다. Completed Step은 앞쪽의 연속된
|
||||
prefix여야 하며 `summary`가 필요하다. Error/blocked는 첫 미완료 Step 하나에만 올 수 있고
|
||||
각각 `error_message`/`blocked_reason`이 필요하다. 뒤 Step은 pending이다.
|
||||
|
||||
Phase/Step 이름은 safe slug여야 하며 directory escape, absolute path, noncontiguous number,
|
||||
unknown status, missing Step file과 duplicate top-level phase는 실행 전에 거부된다.
|
||||
Phase 안의 허용 파일은 index, 선언된 `stepN.md`와 해당 ignored raw output뿐이며 임의 note나
|
||||
미선언 Step file은 metadata ownership을 얻지 않는다.
|
||||
|
||||
## 5. Step 설계
|
||||
|
||||
각 `stepN.md`는 이전 대화 없이 실행 가능한 작업 지시서다.
|
||||
|
||||
```markdown
|
||||
# Step N: <name>
|
||||
|
||||
## Required inputs
|
||||
- architecture와 직접 upstream contract
|
||||
- 이전 Step에서 소비할 exact artifact
|
||||
|
||||
## Owned changes
|
||||
- exact path, type/function과 observable behavior
|
||||
|
||||
## Test-first sequence
|
||||
- 먼저 만들 test와 예상 RED 원인
|
||||
- 최소 GREEN 범위
|
||||
|
||||
## Acceptance commands
|
||||
- focused test
|
||||
- configured build/full test
|
||||
- required comparison
|
||||
|
||||
## Invariants and stop conditions
|
||||
- units, signs, ordering, state, schema, tolerance와 forbidden scope
|
||||
```
|
||||
|
||||
한 Step 안에서 RED를 실제 관찰하고 GREEN/full validation까지 완료한다. “test만 추가” Step과
|
||||
“다음 Step에서 구현”을 분리하면 Stop hook과 phase invariants에 맞지 않는다.
|
||||
|
||||
Planning Agent는 repository configuration과 실제 target을 조사해 command를 적는다. 존재하지
|
||||
않는 target을 예시 command로 대신하지 않는다. Upstream physics/schema/tolerance가 불완전하면
|
||||
Step에 추정값을 넣지 않고 `return-upstream`한다.
|
||||
|
||||
## 6. Executor preflight
|
||||
|
||||
`python scripts/execute.py <phase>`는 Codex 실행 전에 다음을 검증한다.
|
||||
|
||||
1. Harness root와 phase name/path containment 및 exact Git top-level
|
||||
2. Top-level과 phase JSON schema 및 status order
|
||||
3. Implementation Agent profile의 model, reasoning effort와 role instructions
|
||||
4. Sandbox mode와 elevated-run 조건
|
||||
5. Git repository 및 selected phase 밖의 clean worktree
|
||||
|
||||
Pre-existing unrelated tracked, staged 또는 untracked path가 있으면 branch 변경 전에 중단한다.
|
||||
Selected phase의 선언된 plan 파일은 materialization 직후라 아직 dirty일 수 있으며 metadata commit
|
||||
owner는 Executor다. 다른 Git repository 안에 중첩된 framework, 외부로 연결된 phase path와 phase
|
||||
안의 미선언 파일은 거부한다.
|
||||
|
||||
## 7. Branch와 prompt
|
||||
|
||||
Executor는 `feat-<phase>`를 checkout하거나 생성한다. Prompt는 다음을 조합한다.
|
||||
|
||||
```text
|
||||
Implementation Agent developer instructions
|
||||
+ AGENTS.md와 repository guardrail docs
|
||||
+ completed Step summaries
|
||||
+ prior transport failure diagnostic, if any
|
||||
+ current stepN.md
|
||||
```
|
||||
|
||||
Role instructions가 단지 model 선택에만 사용되어서는 안 된다. Source/test write boundary,
|
||||
upstream immutability, skill과 evidence contract가 prompt에 포함된다.
|
||||
|
||||
각 Step은 새 `codex exec` process다. 이전 conversation 전체를 전달하지 않고 approved files와
|
||||
compact summary를 authoritative context로 사용한다.
|
||||
|
||||
## 8. PreToolUse
|
||||
|
||||
PreToolUse input은 current Codex hook contract의 `tool_name`, `tool_input`, `cwd`를 사용한다.
|
||||
|
||||
- Shell 계열은 dangerous command pattern을 검사한다.
|
||||
- Commit, push, checkout/switch, branch, tag와 history-changing Git command는 Executor ownership
|
||||
위반으로 차단한다.
|
||||
- `apply_patch`는 `tool_input.command`의 `*** Add/Update/Delete File`과 `Move to` path를 읽는다.
|
||||
- Edit/Write 계열은 direct path/edits를 읽는다.
|
||||
- Malformed JSON, missing tool/path와 invalid input type은 exit code 2로 fail closed한다.
|
||||
- Production C/C++ path는 config의 roots/patterns로 mapping되는 test가 있어야 한다.
|
||||
|
||||
Hook은 shell redirection 등 모든 write mechanism을 완전하게 인식하지 않는다. Implementation
|
||||
Agent와 code review가 actual RED/GREEN evidence를 계속 책임진다.
|
||||
|
||||
## 9. Stop validation
|
||||
|
||||
Stop hook은 response 직전에 실행된다.
|
||||
|
||||
```text
|
||||
payload/root validation
|
||||
-> project/config discovery
|
||||
-> MSVC toolchain discovery
|
||||
-> adapter validation plan
|
||||
-> configure/build
|
||||
-> test discovery
|
||||
-> full tests
|
||||
```
|
||||
|
||||
모든 subprocess는 `shell=False`, repository-contained working directory와 전체 1,800초 deadline을
|
||||
사용한다. Child process에는 reentry flag를 전달한다.
|
||||
Config의 command/path 문자열에는 control character를 허용하지 않으며 hook 경계의 예상하지 못한
|
||||
일반 예외도 traceback 종료 대신 block response로 변환한다.
|
||||
|
||||
실패 시 stdout에 다음 protocol을 반환한다.
|
||||
|
||||
```json
|
||||
{"decision": "block", "reason": "<actionable validation failure>"}
|
||||
```
|
||||
|
||||
Codex는 같은 session에서 수정할 수 있다. Hook 자체의 malformed payload도 block response이며,
|
||||
`stop_hook_active: true` 또는 child reentry는 재귀를 피하기 위해 바로 허용된다.
|
||||
|
||||
### Project discovery
|
||||
|
||||
1. Explicit `projectType`
|
||||
2. Configured CMake source directory의 preset/CMakeLists
|
||||
3. Root의 한 개 solution 또는 project
|
||||
4. C/C++와 metadata가 모두 없으면 no-target success
|
||||
5. C/C++만 있으면 orphan-project failure
|
||||
|
||||
CMake plan은 MSVC compiler identity와 nonzero CTest inventory를 추가 검사한다. MSBuild plan은
|
||||
repository-relative test executable을 반드시 요구한다.
|
||||
|
||||
## 10. Step result와 transport attempt
|
||||
|
||||
Codex process exit가 0인 경우에만 Step payload를 평가한다.
|
||||
|
||||
- `completed + summary`: stale error/block field를 제거하고 `completed_at` 기록
|
||||
- `error + error_message`: `failed_at` 기록 후 phase error
|
||||
- `blocked + blocked_reason`: `blocked_at` 기록 후 phase blocked
|
||||
- status 미갱신 또는 invalid payload: error
|
||||
|
||||
Nonzero exit가 `completed` payload와 함께 와도 completion을 폐기한다. Authentication/CLI/sandbox
|
||||
helper처럼 분류 가능한 environment failure는 즉시 중단한다. 그 밖의 process/session failure만
|
||||
최대 두 번 transport attempt한다.
|
||||
|
||||
각 attempt 전의 top-level index와 `stepN.md` byte, phase index metadata와 모든 non-current Step을
|
||||
snapshot한다. Session은 current Step의 `status`, `summary`, `error_message`, `blocked_reason`만
|
||||
바꿀 수 있다. 위반 또는 malformed exit payload가 있으면 snapshot을 복원하고 current Step을
|
||||
trusted error로 기록해 재실행 우회를 차단한다.
|
||||
Symbolic branch와 HEAD도 같은 방식으로 비교하며 agent-side commit/checkout은 실패다. Control
|
||||
file read는 link 및 scope escape를 거부하고, 복구와 raw-output write는 atomic replacement로
|
||||
link target overwrite를 방지한다.
|
||||
|
||||
Transport attempt는 implementation correction이 아니다. Implementation/test/reference failure는
|
||||
새 session에서 세 번 자동 수정하지 않고 Coordinator로 반환한다. Coordinator가 동일
|
||||
`feature|gate|classification|contract-revision` key의 Correction Agent를 한 번만 사용할 수 있다.
|
||||
|
||||
## 11. Git ownership
|
||||
|
||||
Step success 시 Executor는 preflight 후 생긴 현재 changes를 다시 분류한다.
|
||||
|
||||
1. Selected phase 밖 implementation paths를 feature commit에 stage
|
||||
2. Selected phase index/Step/timestamps와 top-level index를 metadata commit에 stage
|
||||
3. `stepN-output.json`은 항상 제외
|
||||
|
||||
모든 Git command failure는 fatal이다. Commit 직전에는 working tree를 보존하는 mixed index
|
||||
reset 후 `git add -A`를 pathspec과 `--` 뒤에서만 사용한다. 따라서 pre-staged 파일이 다른 commit에
|
||||
섞이지 않는다. Unicode와 space를 포함한 porcelain path 및 rename의 양쪽 identity는 NUL format으로
|
||||
읽어 ownership을 검증한다.
|
||||
|
||||
Raw output은 local diagnostic이며 `.gitignore` 대상이다. Step 종료 후 implementation path가
|
||||
uncommitted 상태로 남으면 phase finalization을 거부한다.
|
||||
|
||||
모든 Step이 completed이면 phase/top-level `completed_at`을 기록하고 final metadata commit을
|
||||
만든다. `--push`는 사용자가 remote action을 별도로 승인한 경우만 실행한다.
|
||||
|
||||
## 12. Elevated sandbox
|
||||
|
||||
Default는 `workspace-write`다. `danger-full-access`는 다음 조건을 모두 만족해야 한다.
|
||||
|
||||
- 사용자가 exact elevated run을 명시적으로 승인
|
||||
- `FEM_HARNESS_CODEX_SANDBOX=danger-full-access`
|
||||
- `--approve-danger-full-access` flag
|
||||
- primary가 아닌 linked Git worktree
|
||||
- 완전히 clean worktree
|
||||
|
||||
조건 하나라도 없으면 Codex를 실행하지 않는다. Hook trust bypass flag는 등록된 reviewed hook을
|
||||
automation에서 실행하기 위한 것이며 sandbox bypass 권한이 아니다.
|
||||
|
||||
## 13. Recovery
|
||||
|
||||
Error/blocked Step을 임의로 pending으로 돌리기 전에 Coordinator가 evidence를 분류한다.
|
||||
|
||||
| Classification | Route |
|
||||
| --- | --- |
|
||||
| clear implementation defect | bounded implementation fix |
|
||||
| repeated/unclear implementation defect | one Correction allowance, then rerun |
|
||||
| formulation/requirement/reference/I/O defect | owning upstream agent |
|
||||
| toolchain/license/credential | `blocked-environment` or critical user action |
|
||||
| same retry key after correction | no second correction; route or stop |
|
||||
|
||||
재개 시 current Step만 pending으로 변경한다. Executor가 stale summary, failure와 block timestamp를
|
||||
정리한다. Contract revision 없는 문구 변경으로 새 retry key를 만들지 않는다.
|
||||
|
||||
## 14. 검증 evidence
|
||||
|
||||
Harness report는 다음을 기록한다.
|
||||
|
||||
- selected configuration, sandbox와 worktree condition
|
||||
- exact command, cwd, exit code, duration과 output tail
|
||||
- focused RED와 GREEN 결과
|
||||
- full build/test count와 warning
|
||||
- comparison identity/precheck/metric/tolerance result when applicable
|
||||
- commits, ignored raw output와 unexecuted checks
|
||||
|
||||
Hook pass, process exit 0와 agent narrative 중 하나만으로 feature gate를 통과시키지 않는다.
|
||||
Numerical/physics/release owner가 같은 artifact revision을 독립 검토한다.
|
||||
-148
@@ -1,148 +0,0 @@
|
||||
# Product Requirements: Structural FEM Solver Framework
|
||||
|
||||
## 1. 제품 정의
|
||||
|
||||
이 프로젝트는 유한요소 구조해석 솔버를 신뢰성 있게 확장할 수 있는 C++ 해석 코어와
|
||||
그 개발·검증 workflow를 구축한다. 지원하는 해석, 요소, 재료와 입출력 형식은 feature별로
|
||||
명시하며, 구현 여부와 검증 수준을 추적 가능한 evidence로 제공한다.
|
||||
|
||||
현재 repository의 제품은 agent/skill 문서 체계와 C++ 개발 Harness를 포함한 초기
|
||||
framework다. 아직 C++ solver build metadata가 없으므로 특정 해석 기능이 구현되었다고
|
||||
간주하지 않는다.
|
||||
|
||||
## 2. 대상 사용자
|
||||
|
||||
- 구조해석 알고리즘과 요소 정식화를 구현하는 solver 개발자
|
||||
- 해석 결과의 수치 정확성, 물리적 타당성과 회귀를 검토하는 CAE 엔지니어
|
||||
- 입력·결과 형식과 외부 reference model을 관리하는 integration 개발자
|
||||
- 기능별 요구사항, 검증 evidence와 release readiness를 추적하는 maintainer
|
||||
|
||||
## 3. 제품 목표
|
||||
|
||||
1. 해석 물리와 수치 계약을 코드 구조에 명확히 반영한다.
|
||||
2. 작은 요소·재료·해석 기능을 기존 기능을 깨지 않고 단계적으로 추가할 수 있게 한다.
|
||||
3. 동일 입력과 설정에서 재현 가능한 assembly, solve와 output을 제공한다.
|
||||
4. 단위 테스트, analytical/benchmark 검증, mesh convergence, invariant와 독립 reference
|
||||
비교를 결합해 correctness evidence를 축적한다.
|
||||
5. 지원하지 않는 모델 의미를 조용히 근사하지 않고 명확한 진단으로 거부한다.
|
||||
6. agent가 일반적인 설계·구현·검증 결정을 자율적으로 처리하고, 제품 의미를 바꾸는
|
||||
결정만 사용자에게 요청하게 한다.
|
||||
|
||||
## 4. 비목표
|
||||
|
||||
- 특정 상용 solver의 비공개 알고리즘을 복제하는 것
|
||||
- Abaqus 전체 keyword, 모든 element/material/procedure와 bitwise 결과 호환을 약속하는 것
|
||||
- 검증되지 않은 기능을 입력만 받아들이는 형태로 노출하는 것
|
||||
- 하나의 sparse backend, 저장 형식 또는 운영체제를 solver core 계약으로 고정하는 것
|
||||
- 모델 생성용 GUI, CAD geometry kernel, mesher 또는 범용 전후처리기를 초기 범위에 포함하는 것
|
||||
- 외부 결과와 수치가 비슷하다는 사실만으로 물리·수치 정확성을 선언하는 것
|
||||
|
||||
## 5. 핵심 기능 요구사항
|
||||
|
||||
### 5.1 모델 의미
|
||||
|
||||
- Node, element, material, property, set, constraint, load와 analysis step을 명시적 semantic
|
||||
model로 표현해야 한다.
|
||||
- Source label, internal identity, DOF와 equation identity를 구분해야 한다.
|
||||
- 단위계, 좌표계, component 순서와 부호를 입력 및 결과 계약에 기록해야 한다.
|
||||
- 잘못된 참조, 중복 identity, 비유한 값과 지원하지 않는 조합을 analysis 시작 전에
|
||||
진단해야 한다.
|
||||
|
||||
### 5.2 요소 및 재료 확장
|
||||
|
||||
- Element formulation은 kinematics, interpolation, integration, residual/tangent,
|
||||
state variable과 recovery 계약을 함께 제공해야 한다.
|
||||
- Material model은 committed/trial state의 lifetime과 update 실패 의미를 정의해야 한다.
|
||||
- Element나 material 추가가 global assembly, parser 또는 특정 linear algebra backend의
|
||||
변경을 필수로 만들지 않아야 한다.
|
||||
- 각 기능은 적용 범위와 알려진 locking, hourglass, conditioning 또는 convergence 제한을
|
||||
문서화해야 한다.
|
||||
|
||||
### 5.3 해석 절차
|
||||
|
||||
- Analysis procedure는 model validation, DOF 구성, assembly, constraint 적용, solve,
|
||||
convergence 판단, state commit과 result recovery 순서를 소유해야 한다.
|
||||
- Linear/nonlinear, static/dynamic, eigen 또는 contact 계열 기능은 공통 이름 아래 암묵적으로
|
||||
섞지 않고 feature contract로 활성화해야 한다.
|
||||
- 반복해석은 residual과 correction을 구분하고 실패 시 마지막 committed state를 보존해야
|
||||
한다.
|
||||
|
||||
### 5.4 입출력
|
||||
|
||||
- Solver core와 input/output adapter를 분리해야 한다.
|
||||
- 지원 형식과 subset은 versioned contract로 공개해야 한다.
|
||||
- Abaqus `.inp` 호환 feature를 선택한 경우 model data와 history data의 공개 의미를
|
||||
보존하고, 지원 keyword와 option, validation, 미지원 동작을 명시해야 한다.
|
||||
- Unknown semantic construct는 기본적으로 오류이며, 결과에 영향을 주지 않는다고 계약된
|
||||
항목만 warning으로 처리할 수 있다.
|
||||
- 결과는 entity, step/frame, location, coordinate system, component, units와 provenance로
|
||||
식별 가능해야 한다.
|
||||
|
||||
### 5.5 진단과 실패
|
||||
|
||||
- Parser, model, formulation, assembly, solver, convergence, recovery와 I/O 실패를 구분하는
|
||||
structured diagnostic을 제공해야 한다.
|
||||
- 오류에는 가능한 경우 source location 또는 semantic entity identity와 수정 가능한
|
||||
설명을 포함해야 한다.
|
||||
- 실패한 analysis가 부분적으로 authoritative한 결과 파일을 남겨 성공으로 오인되게 해서는
|
||||
안 된다.
|
||||
|
||||
### 5.6 검증과 추적성
|
||||
|
||||
- 모든 필수 requirement는 verification method, acceptance criterion과 evidence에 연결되어야
|
||||
한다.
|
||||
- 수치 feature는 최소한 직접 kernel test와 독립적인 system/benchmark 검증을 가져야 한다.
|
||||
- Reference comparison은 model 의미와 result identity를 먼저 일치시킨 뒤
|
||||
`docs/TOLERANCE.md`에 정의된 metric을 적용해야 한다.
|
||||
- Reference artifact는 read-only이며 구현 결과를 맞추기 위해 수정할 수 없다.
|
||||
- Release verdict는 requirement부터 physics review까지 동일 feature revision의 evidence만
|
||||
사용해야 한다.
|
||||
|
||||
### 5.7 개발 자동화
|
||||
|
||||
- C++ 변경은 실패 test를 먼저 관찰하는 TDD workflow를 따라야 한다.
|
||||
- Harness는 repository 설정에서 build system과 test command를 결정하고 shell string이
|
||||
아닌 검증된 argument list를 실행해야 한다.
|
||||
- 자동화는 사용자의 관련 없는 working-tree 변경을 commit하거나 삭제하지 않아야 한다.
|
||||
- 실패, timeout과 미실행 검사는 성공으로 승격되지 않아야 한다.
|
||||
|
||||
## 6. 품질 속성
|
||||
|
||||
| 속성 | 요구사항 |
|
||||
| --- | --- |
|
||||
| Correctness | 공식화된 방정식, 독립 검증과 물리 invariant로 입증한다. |
|
||||
| Determinism | 동일 platform/config/input에서 ordering과 결과 identity가 재현된다. |
|
||||
| Traceability | Requirement, formulation, code, test, artifact와 verdict를 feature ID로 연결한다. |
|
||||
| Extensibility | Core 변경 없이 adapter/backend를, owner 경계를 깨지 않고 physics 기능을 추가한다. |
|
||||
| Diagnosability | 실패 단계, entity, 원인과 실행 evidence를 구조화해 남긴다. |
|
||||
| Portability | Core C++는 vendor/OS type을 노출하지 않으며 현재 Windows/MSVC baseline을 검증한다. |
|
||||
| Safety | 미지원 의미는 fail closed, artifact 갱신과 외부 변경은 명시적 권한 아래 수행한다. |
|
||||
| Performance | 정확성과 재현성을 먼저 보존하고 측정된 병목에만 최적화를 적용한다. |
|
||||
|
||||
## 7. Feature 완료 조건
|
||||
|
||||
Feature는 다음 조건을 모두 만족할 때만 완료된다.
|
||||
|
||||
- 요구사항과 지원/비지원 범위가 식별 가능하다.
|
||||
- formulation과 numerical review가 같은 convention을 사용한다.
|
||||
- I/O 및 result identity가 versioned contract에 정의되어 있다.
|
||||
- 관련 unit/integration/benchmark test가 통과한다.
|
||||
- 필요한 build, reference comparison과 physics sanity check가 실제로 실행되었다.
|
||||
- 알려진 제한과 미실행 검사가 release evidence에 기록되었다.
|
||||
- 동일 revision의 artifact digest가 handoff chain 전체에서 일치한다.
|
||||
|
||||
## 8. 단계적 제공 원칙
|
||||
|
||||
초기 feature는 하나의 작은 해석 capability를 end-to-end로 완성하는 vertical slice로
|
||||
선정한다. 요소 종류나 analysis family를 넓히기 전에 semantic model, deterministic
|
||||
assembly, diagnostic, result identity와 검증 경로를 먼저 안정화한다. 구체적인 첫 해석
|
||||
기능은 요구사항 단계에서 결정하며 이 PRD가 임의로 선결정하지 않는다.
|
||||
|
||||
## 9. 성공 지표
|
||||
|
||||
- 필수 requirement의 verification evidence 연결률 100%
|
||||
- 지원 feature의 blocking regression test 통과율 100%
|
||||
- 알려지지 않은 semantic input의 silent acceptance 0건
|
||||
- 관련 없는 사용자 파일을 자동화가 수정·commit한 사례 0건
|
||||
- 같은 failure signature의 무한 agent 재시도 0건
|
||||
- release verdict에서 미실행 검사를 통과로 표시한 사례 0건
|
||||
@@ -1,208 +0,0 @@
|
||||
# Structural FEM Solver Agent Design
|
||||
|
||||
## 1. 목적
|
||||
|
||||
이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
|
||||
`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
|
||||
산출물만 소유한다. 기능별 증거는 `docs/features/<feature-id>/`에 보존한다.
|
||||
|
||||
이 계약의 목표는 다음과 같다.
|
||||
|
||||
- 수치적·물리적 책임을 명확히 분리한다.
|
||||
- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다.
|
||||
- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다.
|
||||
- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다.
|
||||
- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다.
|
||||
|
||||
## 2. 권한과 판단 기준
|
||||
|
||||
충돌하는 정보는 다음 우선순위로 판단한다.
|
||||
|
||||
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 -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
|
||||
```
|
||||
|
||||
- Coordinator만 `docs/features/<feature-id>/coordination.md`의 현재 stage, outcome과 next owner를 바꾼다.
|
||||
- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다.
|
||||
- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다.
|
||||
- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한
|
||||
후 기록한다.
|
||||
- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다.
|
||||
- 누락된 증거는 통과로 간주하지 않는다.
|
||||
|
||||
## 4. 단계와 소유권
|
||||
|
||||
| Stage | Owner | Owned outputs |
|
||||
| --- | --- | --- |
|
||||
| `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` |
|
||||
|
||||
`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
|
||||
implementation-owned 파일과 `corrections.md`를 수정한다.
|
||||
|
||||
각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
|
||||
재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
|
||||
`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.
|
||||
|
||||
## 5. 공통 handoff envelope
|
||||
|
||||
모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
|
||||
envelope에는 전이에 필요한 요약만 둔다.
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
필드 규칙은 다음과 같다.
|
||||
|
||||
- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다.
|
||||
- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다.
|
||||
- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다.
|
||||
- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다.
|
||||
- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다.
|
||||
- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다.
|
||||
|
||||
## 6. Outcome과 전이 규칙
|
||||
|
||||
| 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
|
||||
requirements -> research -> formulation -> numerical-review -> io-definition
|
||||
-> implementation-planning -> implementation -> physics-evaluation
|
||||
-> release-readiness -> completed
|
||||
```
|
||||
|
||||
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가 대신 만들지 않았다.
|
||||
|
||||
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를 명확히 기록한다.
|
||||
@@ -1,162 +0,0 @@
|
||||
# Structural FEM Solver Skill Design
|
||||
|
||||
## 1. 목적
|
||||
|
||||
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`다. 공통 workflow와
|
||||
상태 전이는 `docs/SOLVER_AGENT_DESIGN.md`, 수치 비교 정책은 `docs/TOLERANCE.md`가 소유한다.
|
||||
Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다.
|
||||
|
||||
## 2. 설계 원칙
|
||||
|
||||
- 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다.
|
||||
- `SKILL.md`에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다.
|
||||
- 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 `references/`에서 필요한
|
||||
경우에만 읽는다.
|
||||
- Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다.
|
||||
- 산출물은 `docs/features/<feature-id>/`의 공통 feature bundle에 둔다.
|
||||
- 모든 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`으로 반환한다.
|
||||
|
||||
## 3. Workflow skill inventory
|
||||
|
||||
| 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` |
|
||||
|
||||
위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter `name`, agent prompt와
|
||||
`agents/openai.yaml` invocation name은 항상 동일해야 한다.
|
||||
|
||||
## 4. Stage별 책임 분리
|
||||
|
||||
### 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 | 적용 조건 |
|
||||
| --- | --- |
|
||||
| `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는 해당 요청과 권한이 있을 때만 수행한다.
|
||||
|
||||
Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은
|
||||
guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다.
|
||||
|
||||
## 6. 공통 evidence
|
||||
|
||||
Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다.
|
||||
|
||||
- `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
|
||||
|
||||
필요한 명령이 실패했거나 실행되지 않았고 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 부재 또는 미실행을 성공으로 간주하지 않는다.
|
||||
@@ -1,186 +0,0 @@
|
||||
# Numerical Tolerance and Comparison Policy
|
||||
|
||||
## 1. 목적
|
||||
|
||||
이 문서는 구조해석 FEM feature의 solver convergence, regression test와 독립 reference
|
||||
comparison에 사용할 tolerance 선택 절차를 정의한다. 하나의 전역 숫자를 모든 물리량에
|
||||
적용하지 않으며, 각 feature의 Numerical Review가 이 정책에 따라 구체적인 metric과 값을
|
||||
자율적으로 확정한다.
|
||||
|
||||
Tolerance는 결과를 통과시키기 위해 사후 조정하는 값이 아니라 formulation, discretization,
|
||||
reference 품질과 verification 목적에서 도출하는 acceptance contract다.
|
||||
|
||||
## 2. 용어 분리
|
||||
|
||||
다음 값은 서로 대체할 수 없다.
|
||||
|
||||
- **Floating-point tolerance**: 같은 수학 연산의 roundoff 차이를 다룬다.
|
||||
- **Algebraic convergence tolerance**: 선형/비선형 equation solve의 residual 또는 correction
|
||||
종료 조건이다.
|
||||
- **Discretization acceptance**: mesh/order에 따른 FEM 근사 오차와 예상 convergence를 다룬다.
|
||||
- **Reference comparison tolerance**: 독립 결과와 quantity별 차이를 판정한다.
|
||||
- **Physical invariant tolerance**: 평형, 대칭, 보존량 또는 rigid-body behavior를 판정한다.
|
||||
|
||||
Abaqus의 공개된 convergence control과 output convention은 비교 모델의 의미를 맞추는
|
||||
reference로 사용할 수 있지만, 그 convergence criterion을 이 solver의 결과 acceptance
|
||||
tolerance로 그대로 복사하지 않는다.
|
||||
|
||||
## 3. 결정 권한
|
||||
|
||||
Numerical Review는 사용자에게 묻지 않고 다음을 결정할 수 있다.
|
||||
|
||||
- 비교 quantity, identity와 component
|
||||
- absolute/relative/norm/energy/MAC 등 metric
|
||||
- scale과 near-zero 처리
|
||||
- blocking과 diagnostic-only quantity 구분
|
||||
- analytical, convergence 또는 reference evidence에 근거한 수치 tolerance
|
||||
|
||||
다음 경우에만 `needs-user-decision`으로 올린다.
|
||||
|
||||
- 합리적인 두 기준이 동일 결과를 pass와 fail로 나누며 제품 acceptance 의미가 달라지는 경우
|
||||
- tolerance 변경이 지원 범위 또는 공개 정확도 약속을 바꾸는 경우
|
||||
- authoritative requirement/reference artifact가 서로 상충하고 기술 evidence로 우선순위를
|
||||
정할 수 없는 경우
|
||||
|
||||
단순히 기존 결과가 실패했다는 이유는 escalation이나 tolerance 완화 근거가 아니다.
|
||||
|
||||
## 4. Tolerance 선택 우선순위
|
||||
|
||||
1. Requirement 또는 적용 표준이 요구하는 명시적 acceptance
|
||||
2. Exact/analytical/manufactured solution의 알려진 오차와 conditioning
|
||||
3. Mesh/order convergence에서 관찰된 asymptotic error와 기대 rate
|
||||
4. 독립 reference model의 discretization, element formulation, integration/recovery 차이
|
||||
5. 동일 알고리즘 regression의 floating-point 및 backend variation
|
||||
|
||||
낮은 우선순위 근거가 높은 우선순위 기준을 완화하지 않는다. 선택 근거, 단위, scale,
|
||||
mesh와 reference revision을 feature verification 문서에 기록한다.
|
||||
|
||||
## 5. 기본 비교식
|
||||
|
||||
Scalar quantity `x`와 reference `r`는 별도 계약이 없으면 다음 식을 사용한다.
|
||||
|
||||
```text
|
||||
abs_error = |x - r|
|
||||
allowed = atol + rtol * max(|r|, scale_floor)
|
||||
pass = finite(x) and finite(r) and abs_error <= allowed
|
||||
```
|
||||
|
||||
- `atol`, `scale_floor`는 quantity 단위를 가진다.
|
||||
- `rtol`은 무차원이다.
|
||||
- `scale_floor`는 near-zero에서 상대오차가 무한히 커지는 것을 막기 위한 물리적 scale이며
|
||||
임의의 `1.0`을 사용하지 않는다.
|
||||
- NaN/Inf, missing, extra 또는 duplicate required identity는 tolerance 적용 전에 실패한다.
|
||||
- Reference가 exact zero이면 absolute/physical scale 기준을 사용한다.
|
||||
|
||||
Vector 또는 field는 component별 최대오차와 적절한 norm을 함께 기록한다. RMS/평균만으로
|
||||
국부 최대오차를 숨기지 않는다.
|
||||
|
||||
## 6. 검증 유형별 기준
|
||||
|
||||
### 6.1 Exact semantic 및 topology test
|
||||
|
||||
Entity count, connectivity, identity, component order, status code와 schema field는 exact
|
||||
comparison을 사용한다. Floating-point tolerance로 semantic mismatch를 허용하지 않는다.
|
||||
|
||||
### 6.2 Kernel 및 regression test
|
||||
|
||||
- Integer/topological 결과는 exact다.
|
||||
- Floating-point 결과는 operation count, magnitude, conditioning과 backend variation에서
|
||||
tolerance를 도출한다.
|
||||
- 같은 backend/ordering의 deterministic regression은 넓은 engineering tolerance를 쓰지
|
||||
않는다.
|
||||
- 수치 연산 순서가 의도적으로 바뀌면 이전 tolerance를 자동 확대하지 않고 expected envelope를
|
||||
다시 분석한다.
|
||||
|
||||
### 6.3 Analytical, patch와 manufactured solution
|
||||
|
||||
- Polynomial reproduction과 patch-test invariant는 이론상 exact한 차수와 허용 roundoff를
|
||||
구분한다.
|
||||
- Displacement, strain/stress, reaction과 energy 중 formulation을 독립적으로 검출할 수 있는
|
||||
quantity를 선택한다.
|
||||
- Boundary singularity 또는 recovery가 지배하는 지점을 전체 field criterion과 분리한다.
|
||||
|
||||
### 6.4 Mesh/order convergence
|
||||
|
||||
단일 mesh의 우연한 일치보다 최소 세 수준의 refinement가 권장된다. Characteristic size `h`와
|
||||
error `e`로 관찰 차수를 기록한다.
|
||||
|
||||
```text
|
||||
p_observed = log(e_coarse / e_fine) / log(h_coarse / h_fine)
|
||||
```
|
||||
|
||||
기대 rate와 asymptotic range는 formulation 및 quantity norm에 맞춰 feature contract에서
|
||||
정한다. 서로 다른 mesh의 nodal row를 단순 index로 비교하지 않는다.
|
||||
|
||||
### 6.5 Equilibrium과 nonlinear convergence
|
||||
|
||||
- External force/reaction과 internal residual은 동일 좌표계·sign·constraint convention으로
|
||||
정규화한다.
|
||||
- Force residual, displacement correction와 energy check는 각기 다른 failure mode를 보므로
|
||||
하나만으로 대체하지 않는다.
|
||||
- Zero-load 또는 작은-load case는 별도 physical scale을 사용한다.
|
||||
- Solver convergence 성공은 discretization/reference accuracy 성공을 의미하지 않는다.
|
||||
|
||||
### 6.6 Eigenproblem
|
||||
|
||||
- Eigenvalue는 scale-aware absolute/relative error로 비교한다.
|
||||
- Eigenvector는 sign 또는 complex phase 불변성을 고려하고 normalized correlation 또는 MAC을
|
||||
사용한다.
|
||||
- Clustered/repeated eigenvalue는 vector 한 개가 아니라 invariant subspace로 비교한다.
|
||||
- Mode ordering을 frequency index만으로 강제하지 않고 correlation과 multiplicity를 확인한다.
|
||||
|
||||
### 6.7 Dynamic history
|
||||
|
||||
- Time/frequency grid와 interpolation policy를 먼저 계약한다.
|
||||
- Peak, phase, energy, norm과 selected sample을 목적에 맞게 조합한다.
|
||||
- 서로 다른 adaptive increment의 raw frame index를 직접 identity로 사용하지 않는다.
|
||||
|
||||
### 6.8 Stress와 recovered field
|
||||
|
||||
- Integration point, centroid, node extrapolation/averaging 등 output location을 먼저 일치시킨다.
|
||||
- Tensor convention, local orientation와 section point를 key에 포함한다.
|
||||
- Singular point는 regular field tolerance와 분리해 convergence trend 또는 exclusion 근거를
|
||||
명시한다.
|
||||
|
||||
## 7. External reference comparison
|
||||
|
||||
외부 result를 사용하기 전에 다음 equivalence를 확인한다.
|
||||
|
||||
- geometry, mesh와 source identity
|
||||
- element family, order, integration와 stabilization
|
||||
- material/section 및 units
|
||||
- loads, constraints, amplitude와 analysis step
|
||||
- geometric/nonlinear option과 convergence state
|
||||
- result location, coordinate system, averaging와 component convention
|
||||
|
||||
Stored input과 expected result는 read-only다. Reference format은 feature contract가 선택하며
|
||||
특정 CSV/HDF5 layout을 이 정책이 강제하지 않는다. Matching은 semantic key로 수행하고,
|
||||
identity precheck가 통과한 뒤에만 수치 tolerance를 적용한다.
|
||||
|
||||
## 8. 승인 및 변경 규칙
|
||||
|
||||
Feature tolerance record에는 다음을 포함한다.
|
||||
|
||||
- quantity와 physical purpose
|
||||
- metric 식, `atol`, `rtol`, scale 및 units
|
||||
- blocking 여부
|
||||
- 근거 source 또는 convergence evidence
|
||||
- 적용 mesh, formulation, backend와 artifact digest
|
||||
- known exclusions와 diagnostic-only checks
|
||||
|
||||
Implementation Agent는 tolerance를 변경할 수 없다. Numerical Review가 새 evidence로 contract
|
||||
revision을 올리고 영향을 재검토해야 한다. 변경 전 실패 결과와 변경 이유를 보존하며 새
|
||||
기준으로 모든 관련 case를 다시 실행한다.
|
||||
|
||||
## 9. 보고 최소값
|
||||
|
||||
Comparison report는 pass/fail만 기록하지 않고 다음을 남긴다.
|
||||
|
||||
- matched/missing/extra/duplicate/nonfinite 개수
|
||||
- quantity별 최대 absolute/relative error와 발생 identity
|
||||
- 사용한 norm 또는 invariant 값
|
||||
- 허용값과 pass/fail
|
||||
- command, exit code, duration과 input/output digest
|
||||
- 미실행 검사와 제한
|
||||
|
||||
이 evidence가 없으면 tolerance gate는 완료로 간주하지 않는다.
|
||||
@@ -0,0 +1,10 @@
|
||||
Frame: Mode 1: Value = 2.19507E+05 Freq = 74.567 (cycles/time)
|
||||
Frame: Mode 2: Value = 8.85523E+05 Freq = 149.77 (cycles/time)
|
||||
Frame: Mode 3: Value = 8.85523E+05 Freq = 149.77 (cycles/time)
|
||||
Frame: Mode 4: Value = 1.85534E+06 Freq = 216.79 (cycles/time)
|
||||
Frame: Mode 5: Value = 2.74023E+06 Freq = 263.46 (cycles/time)
|
||||
Frame: Mode 6: Value = 2.77515E+06 Freq = 265.13 (cycles/time)
|
||||
Frame: Mode 7: Value = 4.14941E+06 Freq = 324.20 (cycles/time)
|
||||
Frame: Mode 8: Value = 4.14941E+06 Freq = 324.20 (cycles/time)
|
||||
Frame: Mode 9: Value = 6.73379E+06 Freq = 413.00 (cycles/time)
|
||||
Frame: Mode 10: Value = 6.73379E+06 Freq = 413.00 (cycles/time)
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user