modify documents

docs2/ADR.md

@@ -0,0 +1,153 @@
+# 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에 기록한다.