baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify documents

Browse Source
This commit is contained in:
KOKO\Mimi
2026-09-06 00:52:59 +09:00
parent 97e4d7a971
commit ac84235b7a
17 changed files with 2912 additions and 1195 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ADR.md
+279 -308
View File
@@ -1,375 +1,346 @@
# Architecture Decision Records
# FESA Architecture Decision Records
## 철학
FESA의 architecture decision은 solver correctness, verification traceability, implementation testability를 우선한다. Harness는 제품이 아니라 C++/MSVC 기반 FEM 구조해석 솔버 개발을 통제하는 운영 인프라이다.
## 목적과 기록 범위
---
FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한다. 이 문서는 그 과정에서
프로젝트 전반에 적용되는 결정의 이유와 트레이드오프를 관리한다. 제품 목표는
[PRD](PRD.md), 공통 책임과 의존성은 [ARCHITECTURE](ARCHITECTURE.md)를 따른다.
### ADR-001: FESA는 구조해석 솔버 프로젝트이고 Harness는 운영 인프라로 둔다
**결정**: 저장소의 주 목적은 유한요소법 기반 구조해석 솔버 개발이다. Harness는 승인된 Step 계획, 독립 세션 실행, PreToolUse guardrail, Stop MSVC build/test 검증을 제공하는 보조 계층으로 유지한다.
특정 요소·재료·하중·해석 절차의 정식화, 수치 기준과 구현 선택은
`docs/<feature-id>/ADR.md`에 기록한다. 해당 Feature의 목적·범위·acceptance 요약은
같은 폴더의 `PRD.md`, 상세 전문 계약은 requirements·formulation·I/O 등의 소유 문서에 둔다.
공통 ADR에 기능 목록, 진행 상태와 개별 실행 결과를 누적하지 않는다.
**이유**: 기존 문서가 Harness 중심이면 agent가 solver architecture, FEM verification, Abaqus/HDF5 계약보다 운영 스크립트에 과도하게 맞춰 행동한다.
## 기존 결정의 보존과 읽는 방법
**트레이드오프**: Harness 문서의 비중은 낮아지지만, `docs/HARNESS_WORKFLOW.md`의 실행 계약과 `.codex/hooks.json`의 검증 정책은 계속 필수 운영 규칙으로 유지한다.
개정 전 ADR-001~023의 전체 원문은
[원문 보존본](archive/pre-generalization/ADR.md)에 있다. 아래 기존 ID 항목은 그 결정의
공통 부분을 요약한 것이며 번호 재사용, 새 physics 승인 또는 기존 세부 계약의 폐기가 아니다.
구체적인 적용 범위는 원문의 같은 ID와 해당 Feature의 승인된 최신 계약을 함께 확인한다.
### ADR-002: C++17/MSVC/CMake/CTest를 기본 구현 환경으로 둔다
**결정**: 기본 solver 구현과 validation은 C++17 이상, Visual Studio 17 2022 또는
Visual Studio 18 2026 generator, x64 platform, Debug config, CMake, CTest로 수행한다.
`.harness/config.json`이 없으면 CMake가 설치된 두 승인 generator 중 하나를 자동
선택할 수 있으며, build/test evidence에는 실제 generator와 compiler version을 기록한다.
- 과거 결정을 소급 수정하거나 모든 과거 상태를 일괄 `Accepted`로 표시하지 않는다.
- 일부만 대체된 결정은 유지되는 부분과 대체된 부분을 구분한다.
- 현재 선택된 toolchain, 외부 형식과 구현별 계약은 [AGENTS.md](../AGENTS.md) 및 승인된
설정·Feature 계약을 따른다. 문서 일반화만으로 이를 교체하지 않는다.
- 기존 결정 번호는 다른 의미로 재사용하지 않는다. 후속 결정은 마지막 번호 다음으로 추가한다.
- ADR-024~027은 현재 agent·skill·Feature 문서 운영 계약을 기록한다. 새 해석 기능이나
외부 실행 권한을 승인하는 결정이 아니다.
**이유**: FESA의 목표 환경은 Windows/MSVC 기반 C++이다. CMake/CTest는 solver source tree가 추가되거나 확장될 때 가장 일관된 build/test entry point다. VS17과 VS18을
승인하면 현재 지원되는 MSVC 개발 환경에서 같은 C++17/x64/Debug 계약을 검증할 수 있다.
## 프로젝트 공통 결정
**트레이드오프**: FESA solver source는 CMake/CTest를 기본으로 유지한다. Generator별
compiler 차이는 각 build/test report에 명시하고, 두 generator 중 하나에서만 관찰되는
실패를 다른 generator의 성공으로 숨기지 않는다. Harness 자체는 `.harness/config.json`에
solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할 수 있지만, 이는 FESA
제품이 solution-only workflow를 지원한다는 의미가 아니다.
### ADR-001: Solver 제품과 개발 운영 인프라를 분리한다
### ADR-003: Abaqus `.inp` full compatibility가 아니라 기능별 keyword subset을 지원한다
**결정**: FESA parser는 Abaqus keyword/data/comment line 규칙을 따르되, 기능별로 승인된 keyword subset만 지원한다. 미지원 keyword는 명확한 diagnostic을 남긴다.
**결정**: 프로젝트의 제품은 구조해석 솔버다. Agent·skill·Harness는 소스, 문서와
검증 evidence를 관리하는 개발 운영 영역이며 solver runtime의 의존성이 아니다.
**이유**: full Abaqus compatibility는 초기 solver 범위와 검증 비용을 과도하게 키운다. 기능별 subset은 요구조건, I/O contract, reference validation을 추적 가능하게 만든다.
**이유**: 개발 자동화의 편의가 물리적 의미, 사용자 요구와 수치 검증을 대신하지 않게 한다.
**트레이드오프**: 사용자는 기존 Abaqus input file을 그대로 사용할 수 없을 수 있다. 대신 지원 범위와 실패 원인이 명확해진다.
**트레이드오프**: Solver의 완료 evidence와 자동화 자체의 correctness를 별도로 관리해야 한다.
현재 운영 역할과 검증 범위는 ADR-024·026에서 보완한다.
### ADR-004: Domain, AnalysisModel, DofManager, AnalysisState를 분리한다
**결정**: `Domain`은 `ElementDefinition`, `ElementProperty`, `Material`과
`StepDefinition` 입력 모델 정의를 `std::unique_ptr`로 단독 소유하고 const access와
stable collection index를 제공한다. `AnalysisModel`은 Domain 수명 안에서 stable index와
const reference만 사용하는 non-owning current-step view다. `DofManager`는 equation
numbering과 constrained/free mapping을 전담하고, `AnalysisState`는 해석 중 변하는
물리량을 소유한다.
### ADR-002: 구현·검증 환경은 명시된 프로젝트 baseline으로 관리한다
**이유**: 모델 정의, step activation, equation system, transient/nonlinear state가 섞이면 parser, assembler, solver, result writer가 강하게 결합된다. 분리된 상태 모델은 선형 정적 해석에서 시작해 비선형, 동적, thermal coupling으로 확장하기 쉽다.
**결정**: 현재 FESA의 C++ 언어·compiler·platform·build/test baseline을 프로젝트 지침과
설정으로 명시하고 실제 실행 환경을 evidence에 기록한다. 재사용 Harness가 다른
backend를 처리할 수 있다는 사실을 FESA 제품 지원으로 간주하지 않는다.
**트레이드오프**: 초기 class 수가 늘어난다. V0에서는 interface를 얇게 유지하고 실제 선형 정적 frame에 필요한 state만 구현한다.
**이유**: 개발 환경의 암묵적 차이가 build와 numerical regression 판정을 흐리지 않게 한다.
### ADR-005: 공식 결과 파일은 HDF5로 하고 reference 결과는 Abaqus CSV로 둔다
**상태**: HDF5 authoritative output 결정은 유지하며 reference bundle governance 부분은 ADR-019로 대체됨.
**트레이드오프**: 새 환경은 별도의 compatibility와 실행 evidence가 필요하다. 원문의
기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-026의 구성 경계를 따른다.
**결정**: FESA solver의 authoritative result output은 `results.h5` HDF5이다. Abaqus reference results는 기능별 reference model contract가 지정한 `reference/<model-id>/` 아래 CSV 파일로 저장하며, verification은 FESA HDF5 rows와 Abaqus reference CSV rows를 documented IDs, components, units, coordinate system, step/frame identity, tolerance 기준으로 비교한다. 신규 reference는 canonical 파일명을 사용하고, 승인된 기존 bundle의 legacy alias는 해당 기능 계약에 정확한 경로를 기록한 경우에만 허용한다.
### ADR-003: 외부 입력은 승인된 subset의 의미로 지원한다
**이유**: 구조해석 결과는 step/frame, field/history, node/element/integration point location, units, coordinate system, schema version을 함께 가져야 한다. HDF5는 이 계층 구조와 metadata를 안정적으로 표현한다.
**결정**: 외부 형식의 syntax와 semantic mapping을 구분하고 지원·미지원 범위를 명시한다.
미지원 모델 의미는 fail-closed로 진단하며 무해하다고 계약된 항목만 warning/no-op으로 둔다.
**트레이드오프**: reference comparison은 FESA HDF5 dataset identity와 Abaqus CSV row identity를 모두 관리해야 한다. FESA HDF5에서 추출한 deterministic CSV view는 디버깅/검토용 보조 artifact로 허용하지만, 공식 solver output이나 reference artifact로 취급하지 않는다.
**이유**: Parser가 읽을 수 있다는 사실과 물리적으로 해석할 수 있다는 사실은 다르다.
### ADR-006: 해석 알고리즘과 수치 backend는 Strategy와 Adapter 경계 뒤에 둔다
**결정**: `Analysis`, `LinearSolver`, `TimeIntegrator`, `ConvergenceCriteria`는 Strategy로 구성하고, MKL, TBB, HDF5 API는 adapter 계층 뒤에 둔다. `Vector`는 contiguous `double`, `Matrix`는 row-major contiguous `double`을 소유하고 dense 연산은 MKL CBLAS를 사용한다. `SparseMatrix`는 이들과 상속 관계가 없는 0-based CSR 전용 타입이며, PARDISO factorization과 substitution은 `LinearSolver` 경계 뒤에서 분리한다.
**트레이드오프**: 기존 외부 모델을 수정해야 할 수 있지만 silent approximation과 과도한
호환성 약속을 피할 수 있다. 실제 입력 형식의 선택은 기존 승인 계약을 유지한다.
**이유**: 선형 정적, 비선형 정적, 동적, frequency, heat transfer 해석은 공통 흐름을 공유하지만 알고리즘과 backend가 다르다. 외부 API를 core에 노출하면 테스트 double, backend 교체, dependency review가 어려워진다.
### ADR-004: 모델 정의, 실행 view, equation과 mutable state를 분리한다
**트레이드오프**: 단일 기능만 구현할 때는 adapter가 다소 장황해 보일 수 있다. Row-major dense storage와 CSR sparse storage를 따로 유지해야 하지만 backend 의존성과 dense/sparse 의미가 core 모델에 섞이지 않는다.
**결정**: 모델 owner, non-owning 실행 view, DOF/equation owner와 procedure state를
구분한다. View는 원본보다 오래 살지 않으며 승인된 procedure에 필요한 state만 둔다.
### ADR-007: Analysis base는 최소 실행 계약만 제공한다
**결정**: `Analysis` base는 virtual `Analysis::Run(const AnalysisRequest&)`만 제공하고
linear-static-specific protected hook을 정의하지 않는다. 승인된 선형 정적 순서인
`parse input -> initialize Domain -> build AnalysisModel -> build DOF map/sparse pattern ->
assemble stiffness -> partition constraints -> factorize Kff -> assemble load -> form effective
RHS -> substitute -> reconstruct displacement -> recover results -> write HDF5`는
`LinearStaticAnalysis::Run()`의 private lifecycle로 유지한다. 강성행렬 factorization은
하중벡터 조립보다 먼저 수행하고 factorization과 substitution을 하나의 불투명한 solve
호출로 합치지 않는다.
**이유**: Parsing, model activation, numerical solve와 recovery의 수명이 섞이지 않게 한다.
**이유**: 현재 여덟 단계는 linear static equation, state와 failure taxonomy에 특화되어
있다. 최소 base contract는 이 순서의 검증 가능성을 보존하면서 승인되지 않은 dynamic,
eigenvalue 또는 nonlinear procedure에 같은 protected hook과 사용하지 않는 state를
강제하지 않는다. Factorization과 substitution 분리는 동일 강성행렬에 여러 RHS를 적용할
수 있고 각 실패 단계를 구조화된 diagnostic으로 분류하게 한다.
**트레이드오프**: 명시적인 연결과 lifetime 관리가 필요하지만 모델 복사와 분산된
equation numbering, 미래 state의 불필요한 할당을 줄인다.
**트레이드오프**: Procedure 사이의 lifecycle code는 base Template Method로 자동 재사용되지
않는다. 두 번째 procedure가 승인되면 실제로 같은 단계만 focused collaborator로 추출하되,
linear-static hook 사이에 조건문으로 새 physics를 삽입하지 않는다.
### ADR-005: Authoritative result와 reference·debug artifact를 구분한다
### ADR-008: Sparse assembly는 deterministic COO-to-CSR 경로로 시작한다
**결정**: 초기 assembly는 element-local contribution을 COO triplet으로 수집한 뒤 CSR로 finalize한다. MKL PARDISO backend는 CSR input contract를 받는다.
**결정**: 공식 결과의 물리 identity와 versioned 저장 계약을 유지한다. Reference와
debug view를 공식 결과로 대체하지 않는다. 기존 HDF5 선택은 유지하며 보조 형식의 존재가
공식 형식 변경을 뜻하지 않는다.
**이유**: CSR은 MKL PARDISO와 잘 맞고, COO-to-CSR 경로는 구현과 테스트가 명확하다. deterministic reduction은 reference comparison의 재현성을 지킨다.
**이유**: 결과 검토 도구나 비교 편의를 위해 authoritative quantity와 파일 의미가 바뀌는 것을 막는다.
**트레이드오프**: 대규모 모델에서는 메모리와 변환 비용이 생길 수 있다. 성능 문제가 실제로 확인되면 typed batch assembly 또는 kernel 분리를 추가한다.
**트레이드오프**: 물리 identity와 저장 mapping을 함께 관리해야 한다.
원문의 reference naming 규칙은 ADR-019로 대체되었고, 파일명·경로의 후속 결정은
보존본 ADR-023에 있다. 이를 문서 정리 과정에서 과거 값으로 되돌리지 않는다.
### ADR-009: TBB 병렬화는 element-local computation부터 적용한다
**결정**: 첫 oneTBB 적용 지점은 element-local matrix/residual 계산이다. 전역 sparse write는 thread-local buffer 또는 deterministic reduction으로 제한한다.
### ADR-006: 알고리즘과 backend를 명시적인 interface 뒤에 둔다
**이유**: element-local 계산은 독립성이 높고 병렬화 효과가 명확하다. 전역 sparse matrix에 직접 병렬 write하면 재현성, race, ordering 문제가 생긴다.
**결정**: 승인된 analysis와 numerical·parallel·output backend의 계약을 implementation과
분리한다. Vendor/OS 타입과 resource lifecycle은 private adapter에 둔다.
**트레이드오프**: 초기 병렬화 범위가 제한된다. MKL 내부 thread와 TBB task arena의 oversubscription 정책을 별도로 문서화해야 한다.
**이유**: 해석의 물리 의미가 특정 library API와 오류 처리에 종속되지 않게 한다.
### ADR-010: Abaqus reference artifact는 사람이 생성하거나 명시 승인된 절차로만 갱신한다
**상태**: Artifact read-only 및 실행 제한은 유지하며 metadata/provenance/naming 계약은 ADR-019로 대체됨.
**트레이드오프**: Adapter와 계약 테스트 비용이 생긴다. 실제 사용 사례가 없는 Strategy,
factory, 공통 base나 future capability를 미리 도입하지 않는다.
**결정**: Agent는 Abaqus, Nastran 또는 reference solver를 직접 실행하지 않는다. reference artifact 생성, 수정, 복원은 명시 승인된 phase에서만 수행한다. 모든 bundle의 provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance와 limitations는 승인된 기능별 Reference Model Contract에 기록한다. `metadata.json`은 선택 reference artifact이며, 부재만으로 bundle을 불완전하다고 판정하지 않는다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약 및 실제 artifact와 일치하는지 확인하며, 충돌은 숨기지 않고 upstream 계약 문제로 보고한다. 승인된 `cantilever-beam-b33` legacy baseline의 space-containing filename과 `README.md` N/A 예외는 유지한다.
### ADR-007: 해석 procedure가 자신의 lifecycle을 소유한다
**이유**: reference 결과는 solver correctness의 기준이다. 생성 절차가 불명확하면 구현 결함과 reference artifact 오류를 구분할 수 없다.
**결정**: 공통 analysis 경계는 최소 실행 계약만 제공한다. 구체적인 state, assembly,
solve, 반복·종료와 recovery 순서는 procedure별 승인 계약으로 정의한다.
**트레이드오프**: Reference Model Contract가 필수 provenance의 단일 source of truth가 되어 별도 JSON 파일 없이도 bundle을 사용할 수 있다. 선택 `metadata.json`이 계약과 중복될 수 있으므로 존재 시 일관성 검사가 필요하다. Legacy filename과 `README.md` 예외는 일반 artifact 규칙을 복잡하게 하지만 exact path와 source commit을 고정하고 read-only로 취급해 감사 가능성을 유지한다.
**이유**: 서로 다른 해석의 의미를 하나의 고정된 Template Method나 조건문에 강제하지 않는다.
### ADR-011: 구형 단일 검증 진입점 계약을 폐기한다
**트레이드오프**: Procedure 사이의 일부 코드가 중복될 수 있다. 승인된 연산 순서는
보존하며 실제 공통 책임이 확인된 경우에만 collaborator로 분리한다.
**상태**: ADR-012로 대체됨.
### ADR-008: Local contribution과 global assembly를 분리한다
**결정**: 삭제된 legacy validation entry point, legacy Python test discovery, 환경 변수 기반 command override를 Harness의 기본 검증 계약으로 사용하지 않는다.
**결정**: Local 계산은 명시된 ordering으로 contribution을 반환하고, 전역 조립은 지정된
pattern·scatter와 deterministic reduction을 사용한다.
### ADR-012: Harness는 계획, 실행, Hook 검증의 세 계층으로 운영한다
**이유**: 요소 수식과 전역 연결 오류를 분리해 검증하고 scheduling에 의존하지 않게 한다.
**결정**: 계획은 `.agents/skills/harness`, Step 실행과 Git 상태 관리는 `scripts/execute.py`, 도구 호출 전 정책과 종료 전 검증은 `.codex/hooks.json`에 연결된 `scripts/hooks/`가 담당한다. C++ production 변경은 관련 테스트 파일이 있어야 하며, 실제 RED 실패와 GREEN 성공은 같은 Step 안에서 확인한다. Stop은 `.harness/config.json` 또는 자동 감지 결과로 전체 MSVC build/test를 검증한다. Harness Python 변경은 `uv run --with pytest python -m pytest -v -rs`로 검증한다.
**트레이드오프**: Buffer와 변환 비용이 생긴다. 기존 저장·조립 방식의 교체는 별도 evidence와
계약 검토가 필요하며 이 요약은 비결정적인 경로를 허용하지 않는다.
**이유**: 테스트 파일 존재 검사, TDD 실행 증거, 전체 build/test는 서로 다른 책임이다. 이를 분리하면 Hook이 보장하는 범위를 과장하지 않으면서 Step 종료 시 green 상태를 강제할 수 있다.
### ADR-009: 병렬화는 소유권이 명확한 독립 작업에 적용한다
**트레이드오프**: PreToolUse만으로 구현 전 RED 실행을 증명할 수 없으므로 Implementation report에 RED/GREEN 명령과 결과를 기록해야 한다. C/C++가 없는 저장소는 Stop이 통과하므로 Harness Python 검증은 별도 acceptance command로 유지한다.
**결정**: Worker는 자신의 local output에만 기록하고 공유 결과의 reduction과 diagnostic
선택은 결정적으로 수행한다.
### ADR-013: V0 선형 정적 해석은 단일 step B33 Euler beam으로 제한한다
**이유**: Race와 부동소수 누적 순서가 물리 검토·회귀 비교를 흔들지 않게 한다.
**결정**: 첫 end-to-end 제품 기능은 입력 파일당 하나의 `*STEP, *STATIC`을 해석하는 2절점 3D Euler–Bernoulli beam이다. Abaqus `TYPE=B33`만 이 요소로 매핑하고 B31은 `unsupported-element-formulation`으로 거부한다. `*PART/*ASSEMBLY/*INSTANCE`는 여러 identity instance와 stable source identity를 지원하지만 instance transform, nested assembly, 다중 step은 지원하지 않는다. Output-request keyword는 승인 allowlist에서 warning 후 no-op 처리하고 FESA 기본 HDF5 결과는 항상 생성한다.
**트레이드오프**: 병렬화 범위와 throughput이 제한될 수 있다. Backend thread와 task
정책은 실제 측정과 검증을 통해 정하며 승인된 ordering을 보존한다.
**이유**: B31은 transverse shear deformation을 포함하므로 Euler–Bernoulli 정식화와 의미가 다르다. 단일 step과 identity instance로 범위를 제한하면 parser wrapper, source identity, assembly, 해법 및 결과 복구를 end-to-end로 검증하면서 의미를 왜곡하지 않는다.
### ADR-010: 외부 reference는 명시적인 소유권과 권한 아래 유지한다
**트레이드오프**: 기존 Abaqus 모델 중 B31, instance transform, 다중 step 또는 `*DLOAD`를 사용하는 입력은 거부된다. 이후 기능은 별도 요구조건과 formulation/reference gate를 거쳐 추가한다.
**결정**: 저장된 reference는 read-only다. 생성·수정·복원과 외부 solver 실행은 명시적으로
승인된 범위에서만 다루며, 구현을 통과시키기 위해 artifact를 보정하지 않는다.
### ADR-014: B33 cantilever baseline은 component-scale 혼합 tolerance로 비교한다
**이유**: 검증 기준과 구현 결과가 서로를 정당화하는 순환을 방지한다.
**상태**: Artifact inventory와 component mapping의 역사적 결정은 유지하며 tolerance와
node-station projection 결정은 ADR-022로 대체됨.
**트레이드오프**: 필요한 artifact가 없으면 적절한 owner나 환경 조치가 필요하다.
원문의 추가 metadata·provenance·naming 조건은 ADR-019로 대체되었다.
**결정**: `reference/cantilever beam/`의 B33 input, displacement CSV, reaction CSV, elemental-force CSV를 V0 reference baseline으로 사용한다. Displacement와 reaction은 node identity로, section resultant는 CSV node station과 정규화된 FESA element endpoint로 비교한다. 같은 model, step/frame, quantity, component에 대해 `reference_scale = max(abs(reference rows))`를 계산하고 모든 row에 `absolute_floor + 1e-6 * reference_scale`을 적용한다. SI displacement/rotation absolute floor는 `1e-9`, force/moment floor는 `1e-3`이다. Beam stress는 출력하되 Abaqus stress reference comparison은 N/A다.
### ADR-012: 계획, 실행과 Hook 검증의 책임을 분리한다
**이유**: 자유단 moment처럼 이론적으로 0인 값에는 행별 상대오차가 정의되지 않으며 Abaqus 결과에 작은 수치 잔차가 남을 수 있다. Component scale을 사용하면 전체 물리량 크기에 비해 작은 잔차를 허용하면서 각 row를 결정적으로 판정할 수 있다.
**결정**: Planning은 할당된 계획 파일, Executor는 실행 상태와 Git 처리, Hook은 등록된
guardrail과 종료 검증을 담당한다. 테스트 파일 존재는 RED 관찰의 증거가 아니다.
**트레이드오프**: 큰 component scale은 zero row의 허용폭을 넓힌다. 이를 완화하기 위해 quantity와 component를 섞지 않고 Abaqus 값만 scale에 사용하며, 모든 row의 absolute/normalized error와 worst row를 보고하고 누락·추가·nonfinite row를 tolerance 전에 실패시킨다.
**이유**: 자동화 각 계층이 보장하는 범위를 명확히 하여 검증 누락과 과장된 통과 판정을 막는다.
### ADR-015: 외부 CMake target을 FESA 경계로 정규화하고 Windows runtime closure를 명시한다
**트레이드오프**: Implementation은 실제 명령·결과를 별도 evidence로 남겨야 한다.
원문의 전체 Stop 검증 설명은 ADR-026의 조건별 검증 범위와 함께 읽고, 계획·실행의
권한은 ADR-024의 현행 운영 계약을 따른다.
**결정**: MKL, TBB, HDF5 CONFIG package가 제공하는 target은 dependency module에서
`Fesa::MKL`, `Fesa::TBB`, `Fesa::HDF5`로 정규화한다. Product target은 이 경계만
`PRIVATE` link하고 public header에 vendor/Win32 type을 노출하지 않는다. Approved Windows
환경에서는 packaged shared HDF5 C target을 우선하며, CLI와 test executable 옆에 TBB,
MKL, OpenMP, Intel math runtime, HDF5를 포함한 실제 runtime DLL closure를 POST_BUILD로
stage한다.
### ADR-015: Build dependency와 runtime closure를 명시한다
**이유**: Package version이나 shared/static variant에 따라 imported target 이름과 숨은
runtime dependency가 달라질 수 있다. Configure와 link 성공만 확인하면 GoogleTest
discovery 또는 배포된 CLI가 `0xc0000135`로 실패할 수 있다. FESA-owned target과 명시적
runtime closure는 module code와 실행 환경을 package 세부사항에서 분리한다.
**결정**: 외부 dependency를 프로젝트가 소유한 target 경계로 정규화하고 public API에
vendor type을 노출하지 않는다. 실행에 필요한 dynamic dependency도 검증 범위에 포함한다.
**트레이드오프**: Windows staging CMake가 길어지고 새 dynamic dependency마다 runtime
audit가 필요하다. 대신 개인 설치 경로를 source에 하드코딩하거나 developer `PATH`에
의존하지 않고 build tree executable을 재현 가능하게 실행할 수 있다.
**이유**: Configure·link 성공만으로 실제 실행 환경의 완전성을 증명할 수 없다.
### ADR-016: 결정론과 failure atomicity를 correctness contract로 취급한다
**트레이드오프**: Backend 추가마다 build 및 runtime 검토가 필요하다. 구체적인 package
선택·staging 구현은 현재 설정과 기존 승인 계약에 유지한다.
**결정**: Parallel element 계산은 index별 독립 buffer만 쓰고, COO tuple ordering과
floating-point sum은 join 이후 고정된 serial 순서로 수행한다. Result recovery, solver
output, HDF5 writer는 candidate를 완성·검증한 뒤 caller-owned state 또는 final file에
commit한다. HDF5는 same-directory temporary file을 checked close/reopen한 후에만 atomic
finalization한다.
### ADR-016: 결정론과 failure preservation을 correctness로 취급한다
**이유**: Reference comparison과 물리 검토는 row identity와 작은 수치 차이에 민감하다.
Thread scheduling 또는 중간 실패가 sparse bytes, result order, 이전 output을 바꾸면 같은
입력에 대한 evidence를 신뢰할 수 없다.
**결정**: Ordering과 reduction을 명시하고, state·result·final output은 검증된 candidate를
통해 반영한다. 실패 시 계약된 기존 유효 상태와 최종 결과를 보존한다.
**트레이드오프**: Serial reduction과 candidate copy가 throughput과 memory를 더 사용할 수
있다. 성능 최적화는 동일한 ordering, failure preservation, reference 결과를 증명할 때만
대체할 수 있으며, nondeterministic global sparse write는 허용하지 않는다.
**이유**: 재현 가능한 결과와 실패 후 신뢰할 수 있는 상태가 검증의 전제이기 때문이다.
### ADR-017: Essential constraint는 stable elimination으로 적용하고 reaction은 full residual로 정의한다
**트레이드오프**: Buffer, candidate와 검증 비용이 증가한다. 성능 개선은 같은 보존
경계와 결과 의미를 입증해야 하며 correctness를 약화하는 예외로 처리하지 않는다.
**결정**: V0는 DofManager의 stable free/constrained order로 full stiffness를
`Kff/Kfc/Kcf/Kcc`로 분할하고 `Kff * df = Ff - Kfc * dc`를 푼 뒤 full displacement를
복구한다. 모든 DOF가 constrained인 모델의 `0 x 0 Kff`는 유효한 trivial factorization과
empty substitution이다. Recovery의 full residual `r = K*d - F`를 reaction vector로
보존하며 constrained entry는 physical reaction, free entry는 equilibrium evidence다.
### ADR-017: 제약 적용과 reaction 의미를 equation 계약으로 정의한다
**이유**: Equation numbering과 prescribed displacement를 한 owner가 관리하면 nonzero
constraint, no/all/mixed constraint가 같은 수식과 stable order를 사용한다. Full residual은
element end action을 별도로 합산하는 경로보다 조립·하중·해법 전체의 equilibrium을 직접
검증한다.
**결정**: DOF mapping, 제약 적용, 해 복구, residual과 reaction의 의미를 명시적인
수학 계약으로 묶는다. Node/Element에 equation 번호를 분산 저장하지 않는다.
**트레이드오프**: Full K와 네 partition을 유지하는 메모리 비용이 있고 reaction vector의
free entry가 정확한 0이라고 가정할 수 없다. V0에는 penalty, MPC, Lagrange multiplier를
혼합하지 않으며, 추가 constraint policy는 별도 formulation과 equation/output 계약을
요구한다.
**이유**: 서로 다른 space나 enforcement 방식의 값을 같은 물리량으로 오인하지 않게 한다.
### ADR-018: Kernel 존재와 제품 노출을 분리하고 계층형 검증을 요구한다
**트레이드오프**: 새 constraint 방식은 equation과 output의 영향을 함께 검토해야 한다.
원문에 있는 기존 elimination·full-residual 결정은 해당 기능 범위에서 계속 유지되며,
이 공통 요약이 다른 방식을 기존 구현에 적용할 권한을 주지 않는다.
**결정**: Local element/load/recovery kernel이 존재해도 syntax, semantic Domain mapping,
analysis orchestration, mandatory HDF5와 diagnostic 계약이 연결되지 않으면 CLI 지원으로
간주하지 않는다. 검증은 unit, integration, reference comparison, physics sanity를 서로
대체할 수 없는 계층으로 유지한다. Reference가 가능하지 않은 quantity는 명시적 N/A와
analytical/schema/physics 대체 evidence를 요구한다.
### ADR-018: Kernel 존재와 제품 노출을 구분하고 계층형 검증을 요구한다
**이유**: Unit test는 수식과 validation을, integration test는 lifetime과 호출 순서를,
reference comparison은 외부 solver와의 수치 일치를, physics sanity는 공통-mode 오류와
model adequacy를 검출한다. 한 계층의 성공만으로 parser exposure 또는 물리 correctness를
추론하면 지원 범위와 검증 강도가 과장된다.
**결정**: 입력 의미, 내부 해석, 결과·진단과 필수 검증이 연결되어야 제품 기능으로 다룬다.
Local test, integration, reference 비교와 독립 물리 검토는 서로를 대체하지 않는다.
**트레이드오프**: 작은 기능도 여러 계약과 evidence를 함께 준비해야 하므로 개발 속도가
느려진다. 대신 `*DLOAD`처럼 kernel은 있지만 입력에 노출되지 않은 기능, stress처럼
mandatory output이지만 Abaqus reference가 N/A인 기능을 정확하게 표현할 수 있다.
**이유**: 부분 구현이나 외부 수치 일치만으로 제품 지원과 correctness가 과장되는 것을 막는다.
### ADR-019: Abaqus는 입력 형식과 외부 수치 reference이며 FESA 내부 동작 계약이 아니다
**결정**: FESA는 Abaqus와 독립적인 솔버다. 기능별 승인 `.inp` subset을 입력으로
사용하고, 기능이 blocking으로 선언한 FESA HDF5 quantity만 기존 Abaqus CSV와 승인
tolerance로 비교한다. Abaqus 요소 정식화, 적분, stabilization, 내부 상태와 결과 생성
절차를 재현하거나 동등하게 구현하지 않는다. Exact numerical equality는 허용되지만
내부 동작 동등성의 evidence가 아니다.
Reference case readiness에는 선언된 `.inp`, 실제 비교에 필요한 CSV, deterministic
source-ID/component matching과 tolerance만 필요하다. 기존 path와 filename을 그대로
사용하며 canonical naming, legacy-alias 승인, bundle `README.md`, `metadata.json`, Abaqus
version/provenance, 중복 units/coordinates/model/step/frame/material/section 정보와 CSV schema
version은 요구하지 않는다. Reference artifact는 계속 read-only이며 누락, 추가, 중복,
nonfinite required row는 tolerance 전에 실패한다.
**이유**: Reference comparison의 목적은 FESA의 독립 정식화가 승인된 observable quantity를
충분히 가깝게 계산하는지 판정하는 것이다. 수치 비교에 사용되지 않는 artifact
거버넌스가 formulation review나 implementation planning을 차단하면 제품 검증보다 문서
형식 준수가 우선된다. 같은 정보는 `.inp`, CSV header와 feature contract에서 직접 얻을
수 있다.
**트레이드오프**: Reference 생성 환경을 사후에 완전히 재구성하는 감사 기능은 줄어든다.
대신 비교 대상과 source-row/component mapping, tolerance, artifact immutability는 유지해
false match와 결과 보정을 방지한다. 더 강한 provenance가 필요한 기능은 해당 요구조건이
명시적으로 추가할 수 있으나 프로젝트 기본 gate로 자동 승격하지 않는다.
### ADR-020: MITC4 displacement reference는 고정 절대오차로 판정한다
**상태**: S4 artifact 선택과 U blocking/UR warning-only 분류는 유지하며 고정 절대오차
결정은 ADR-022로 대체됨.
**결정**: Full-integration FESA-MITC4의 sole S4 reference comparison은 matched global
`U1/U2/U3` row에 고정 절대오차 `1.0e-5`를 적용해 pass/fail을 판정한다.
`UR1/UR2/UR3`도 고정 절대오차 `1.0e-5`로 비교하지만 초과는 deterministic warning만
생성한다. Reference scale은 보고용 통계로 남을 수 있으나 MITC4 row tolerance 또는
normalized error의 분모를 결정하지 않는다. ADR-014의 B33 component-scale 혼합
tolerance는 변경하지 않는다.
**이유**: Abaqus S4는 FESA-MITC4와 동일한 요소 정식화가 아니므로 B33에서 승인한 매우
엄격한 component-scale tolerance를 그대로 재사용하는 것은 독립 솔버의 observable
displacement 검증 목적에 맞지 않는다. 고정 절대오차는 현재 사용자 단위계에서 승인된
차이를 명시적으로 제한하면서 zero clamp나 row omission 없이 모든 displacement row를
동일하게 판정한다.
**트레이드오프**: Model scale이 크게 달라지면 고정 절대오차의 상대적 엄격도가 달라질 수
있다. 따라서 이 값은 현재 승인된 MITC4 S4 case의 기능 완료 기준이며 개발 완료 후
별도 reference-verification evidence와 함께 재점검한다.
### ADR-021: Semantic definition과 runtime solver contract를 분리한다
**결정**: Domain-owned semantic definition과 analysis-time numerical object를 다음
dependency 방향으로 분리한다.
```text
Domain owns ElementDefinition / ElementProperty / Material / StepDefinition
AnalysisModel is a non-owning stable-index view into Domain
ElementFactory creates runtime Element candidates from compatible definitions
DofManager -> ElementDofLayout
SparseAssembler -> ElementStiffnessContribution
ResultRecovery -> ElementResultBundle
LoadAssembler -> ordered LoadContribution
EssentialConstraintPolicy -> ConstraintDefinition
Analysis <- LinearStaticAnalysis
```
`Domain`의 polymorphic semantic collection은 `std::unique_ptr` 단독 ownership과 stable
vector position을 사용한다. `ElementDefinition`은 source identity, connectivity와
property/material identity를 제공하고 runtime `Element`는 DOF layout, stiffness와 result
recovery를 제공한다. `ElementFactory`가 definition/property/material compatibility를
중앙에서 검사하며 unknown 또는 incompatible 조합은 fail-closed diagnostic으로 거부한다.
Consumer는 B33/MITC4 concrete type branch를 분산시키지 않고 runtime contract를 사용한다.
Linear-static candidate가 runtime `Element`를 `std::unique_ptr`로 소유하고 consumer는 그
수명에 한정된 non-owning view만 사용한다.
`Material` base에는 identity, source location과 lifetime 이외의 future capability를
추가하지 않는다. 현재 isotropic linear elasticity가 실제로 요구하는 data는 concrete
material에 둔다. Density, anisotropy, plastic state, temperature와 rate dependency는
optional field 또는 no-op virtual method로 미리 할당하지 않는다. `ElementProperty`도
현재 beam/shell 의미를 각 concrete type에 둔다.
`Load`는 ordered `LoadContribution`을 생성하고 global full-DOF accumulation은
`LoadAssembler`가 단독 소유한다. `BoundaryCondition`은 `ConstraintDefinition`을 생성하고
`EssentialConstraintPolicy`가 prescribed-displacement elimination과 reconstruction을
소유한다. Distributed/body load와 MPC/penalty/Lagrange-multiplier enforcement는 이번
결정으로 구현된 기능이 아니다.
Abaqus Domain mapper, result recovery와 HDF5 writer는 기존 public facade를 유지하면서
각각 topology/material-property/step-final-assembly, equilibrium/beam/shell/atomic-state,
RAII/model-result-dataset/self-check/atomic-finalization 책임으로 private implementation을
나눈다.
**이유**: Semantic identity와 runtime kernel을 같은 concrete record에 두면 DofManager,
SparseAssembler, ResultRecovery, parser와 output이 B33/MITC4 storage를 함께 알아야 한다.
Definition/factory/runtime contract와 contribution/policy 경계를 분리하면 stable source
identity와 deterministic reduction owner를 유지하면서 실제 두 element 구현을 공통
consumer로 연결할 수 있다. Focused facade 분할은 외부 계약을 바꾸지 않고 큰 translation
unit의 서로 다른 failure-atomicity 책임을 검토 가능하게 한다.
**트레이드오프**: Base object, factory와 contribution record가 늘고 checked compatibility에
한 단계의 indirection이 생긴다. 대신 `std::shared_ptr`, speculative `Clone()`, global
registry와 future-only material/analysis capability는 도입하지 않는다. B33/MITC4의 승인된
formulation, 연산·reduction 순서, sign, units, coordinates와 result identity가 이
리팩터링보다 우선하며 HDF5 schema, reference artifact와 ADR-014/ADR-020 tolerance는
변경하지 않는다. MITC3, solid, dynamic과 plastic behavior는 별도 feature gate 전까지
구현된 것으로 간주하지 않는다.
### ADR-022: 외부 reference comparison은 공통 family-scale 정책을 사용한다
운영 상수, 검증 순서, report schema와 변경 관리는 `docs/TOLERANCE.md`를 따른다.
**결정**: B33, MITC4와 이후 기능의 외부 reference comparison은 동일한 무차원 수치
정책을 사용한다. 같은 model/case, step/frame, logical quantity, unit dimension, coordinate
system과 blocking behavior의 component family에 대해 reference-only scale
`S=max(abs(reference))`를 계산한다. `abs(reference)<=0.01*S`인 행은
`abs(fesa-reference)<=0.01*S`, 나머지 행은 `abs(fesa-reference)/abs(reference)<=0.05`를
만족해야 한다. 모든 행과 함께 family scale-relative RMS `RMS(error)/S<=0.01`도
통과해야 한다. 독립 absolute-error gate는 두지 않으며 `S=0`이면 모든 FESA 값도 exact
zero일 때만 통과한다.
B33 family는 translation, rotation, reaction force, reaction moment, section force와
section moment로 구분한다. 2026-08-18에 다시 생성된 elemental-force CSV의
`Element Label`과 `Node Label`을 사용해 `(instance, element, endpoint node, component)`를
HDF5 endpoint에 직접 대응하고 node-station collapse나 평균을 사용하지 않는다. MITC4는
translation `U1/U2/U3` family를 blocking으로, rotation `UR1/UR2/UR3` family를
warning-only로 유지한다.
**이유**: Feature별 absolute floor와 fixed absolute tolerance는 모델 단위와 크기에 따라
서로 다른 엄격도를 만들었다. 개별 component scale은 물리적으로 zero-like인 MITC4
`U1/U2` residue를 자체 scale로 만들어 잘못 실패시킨다. 동일 차원의 family scale,
near-zero 대체 분기와 relative RMS를 결합하면 zero row의 불안정한 raw relative error를
피하면서 모든 행과 전체 오차 수준을 함께 검사할 수 있다. B33의 element-endpoint identity는
reference와 HDF5가 제공하는 실제 source identity를 보존한다.
**트레이드오프**: Family 최대값이 작은 component의 허용폭을 결정하므로 행별 relative
gate와 family RMS gate를 모두 유지해야 한다. Reference family 전체가 zero이면 별도
절대 scale이 없으므로 exact-zero만 허용하는 엄격한 fail-closed 정책이 된다. 기존 B33과
MITC4 verification report 및 comparator schema는 새 정책에 맞춰 다시 생성해야 하지만
reference artifact, HDF5 schema, element formulation과 blocking/warning 분류는 변경하지
않는다.
### ADR-023: Nonlinear Static은 prepared dispatch와 accepted-frame evidence로 분리한다
**결정**: CLI는 하나의 `.inp` operand만 받고 input lexical sibling
`<stem>_results.h5`와 `<stem>_log.txt`를 유도한다. `--output`은 지원하지 않는다.
`PrepareAnalysisInput()`이 syntax/semantic map을 한 번만 수행하고, prepared Domain의
procedure identity가 linear static 또는 separate nonlinear full-Newton procedure를 선택한다.
Nonlinear procedure는 trial/committed state, unsymmetric tangent solver와 iteration log를
독립적으로 소유하며 log close 뒤에만 schema-v1 HDF5 writer가 accepted frames를 atomic publish한다.
schema-v1 `/global/equilibrium`의 six values는 global origin `[0,0,0]`에서 current `X+u`
force arm과 spatial physical nodal moments를 쓴 applied-plus-constrained-reaction balance
error다. Accepted free generalized residual과 constrained-reaction resultant는 distinct
projections이며 result dataset을 서로 대체하지 않는다. Nonlinear reference portfolio는 fine
primary `shellNL-meshfine`, coarse companion `shellNL`, linear control `shell`을 분리한다.
External U is blocking, UR is warning-only, local RF/RM is review-only, and RM3/stress is excluded;
the factor-one internal global force/moment balance and accepted free residual remain blocking.
**이유**: Input parse, linear lifecycle, nonlinear trial state와 writer finalization을 한
procedure에 섞으면 output lifetime과 failure atomicity를 검증할 수 없다. Applied-plus-reaction
balance, constrained reaction과 free residual을 구분하면 nonzero prescribed translation/rotation
case에서도 force arm, mask와 rotation-coordinate conversion의 의미가 보존된다.
**트레이드오프**: Nonlinear path는 linear procedure보다 state/backend/writer 수가 늘고 fine
reference run 시간이 길다. 대신 HDF5 authoritative output, immutable CSV artifact와 external
solver internal-algorithm non-equivalence 원칙을 유지하며 local support-force distribution을
blocking tolerance로 위장하지 않는다.
**트레이드오프**: 작은 기능도 여러 종류의 evidence가 필요하다. Reference N/A는 이유와
승인된 대체 근거를 기록하며, 모든 기능에 동일한 benchmark 목록을 강제하지 않는다.
### ADR-019: 외부 solver의 관찰 가능한 의미와 내부 동등성을 구분한다
**결정**: 외부 제품의 공개 입력 의미와 승인된 출력량은 reference로 사용할 수 있지만
비공개 알고리즘·상태·결과 생성 절차를 추정하거나 동등성을 주장하지 않는다.
수치적 exact equality는 허용되지만 내부 동등성의 증거가 아니다.
필요한 source identity·component와 비교 artifact를 사용하며 기존 path와 값을 보존한다.
Canonical naming이나 중복 metadata·provenance를 기본 readiness gate로 추가하지 않는다.
이는 ADR-005·010의 관련 부수 조건을 대체하며 artifact immutability는 유지한다.
**이유**: 물리·수치 검증보다 외부 제품의 비공개 동작 추정이나 문서 형식 맞추기가 앞서지 않게 한다.
**트레이드오프**: 더 강한 provenance가 필요한 경우 별도 명시적 요구가 필요하다.
기본 비교에서도 누락·추가·중복·nonfinite 값과 잘못된 identity는 거부한다.
### ADR-021: Semantic definition과 runtime numerical contract를 분리한다
**결정**: 모델 정의는 identity와 입력 의미를 소유하고, runtime numerical object는
승인된 evaluation·contribution·recovery 계약을 제공한다. 생성 경계가 호환성을 검사한다.
**이유**: Parser와 global consumer가 모든 concrete element/material storage를 알 필요가
없도록 하면서 source identity와 명시적 소유권을 유지한다.
**트레이드오프**: Indirection과 compatibility 검증이 필요하다. Speculative cloning,
global registry와 future-only capability를 도입하지 않는다. 원문 리팩터링의 구현별
설명은 보존본에 있으며 당시 tolerance 참조는 후속 ADR-022와 함께 읽는다.
### ADR-022: 외부 reference comparison에 승인된 공통 정책을 적용한다
**결정**: 외부 reference의 family, scale, near-zero·row·RMS·zero-scale 판정과 보고·변경
관리는 [TOLERANCE](TOLERANCE.md)를 따른다. 기능별 비교량과 identity는 해당 Numerical
Review 및 I/O 계약으로 정의한다. 이 문서는 수치 상수와 판정식을 중복 유지하지 않는다.
**이유**: 기능마다 임의의 scale이나 오차 기준을 적용하거나 구현 결과에 맞춰 기준을
완화하는 일을 방지한다.
**트레이드오프**: 변경 시 관련 comparator와 evidence를 함께 재검증해야 한다.
ADR-014·020의 과거 수치 정책을 대체하지만 artifact 선택·identity·판정 영향 중 유지되는
부분은 원문과 후속 계약을 확인한다. 이번 일반화는 tolerance 변경이 아니다.
## 기능별·대체된 결정의 이관 기록
다음 ID는 프로젝트 공통 결정으로 다시 정의하지 않는다. 원문은
[보존본 ADR](archive/pre-generalization/ADR.md)의 같은 ID에 있으며, 향후 해당
`docs/<feature-id>/ADR.md`를 작성할 때 원래 ID·범위·revision과 대체 관계를 연결한다.
아직 작성하지 않은 Feature ADR을 존재하거나 승인된 문서처럼 링크하지 않는다.
| 기존 ID | 보존할 범위와 상태 | 이관 또는 조회 대상 |
| --- | --- | --- |
| ADR-011 | 구형 검증 진입점 폐기 이력; ADR-012로 대체됨 | 프로젝트 운영 이력 |
| ADR-013 | 최초 end-to-end 기능의 입력·해석 범위 결정 | `linear-static-3d-euler-beam` Feature ADR |
| ADR-014 | 최초 reference baseline 및 비교 계약 이력; tolerance와 projection은 ADR-022로 대체됨 | `linear-static-3d-euler-beam` Feature ADR |
| ADR-020 | 요소 확장의 reference 선택·판정 구분 이력; 수치 정책은 ADR-022로 대체됨 | `linear-static-mitc4-shell` Feature ADR |
| ADR-023 | 별도 procedure, accepted-frame 결과와 CLI 경로 결정 | `nonlinear-static-newton-raphson` Feature ADR; 공통 외부 경로의 후속 결정 근거로도 보존 |
원문의 결정 당시 상태를 현재 release verdict로 해석하지 않는다. 후속 Feature가 범위를
확장했거나 evidence가 stale인 경우 해당 승인 계약과 workflow 상태를 따로 확인한다.
## 공통 개발 운영 결정
### ADR-024: Coordinator가 evidence 기반 workflow와 유한 correction을 소유한다
**상태**: 현재 [agent 운영 계약](SOLVER_AGENT_DESIGN.md)의 기록.
ADR-012의 계획·실행·검증 계층을 보완하며 specialist의 계약 소유권을 변경하지 않는다.
**결정**: Coordinator만 상태를 전이하고 specialist는 할당된 전문 판단과 산출물을
반환한다. 승인된 scope 안의 일반 작업에는 반복 승인 gate를 추가하지 않고 critical
decision만 사용자에게 요청한다. 계획 요청 자체는 실행 권한이 아니다.
동일 normalized `retry_key`의 correction은 한 번으로 제한하고 이후 Implementation
rerun을 한 번 수행한다. Executor transport attempt와 이를 혼용하지 않는다.
필수 evidence가 누락·실패·stale이면 통과시키지 않는다.
**이유**: 일상적인 handoff의 승인 병목을 줄이면서 제품 의미와 외부 권한을 사람이
통제하고, 같은 실패를 무한 반복하지 않게 한다.
**트레이드오프**: Owner, revision, evidence와 실패 signature를 명확히 기록해야 한다.
Release readiness가 외부 게시나 배포 권한을 주지는 않는다.
### ADR-025: 프로젝트 기준과 Feature 문서의 원본·소유권을 분리한다
**상태**: 현재 [Feature 문서 관리](FEATURE_DOCUMENTATION.md) 계약의 기록.
**결정**: 프로젝트 PRD·ARCHITECTURE·ADR에는 공통 기준만 둔다. Coordinator는
Feature의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md`와 문서
목록·링크를 관리하고 specialist는 자신의 전문 본문과 상세 문서를 소유한다.
상태 원본은 `coordination.md`, 상세 요구사항 원본은 `requirements.md`다.
`FEATURED_AGENTS.md`는 자동 로드되는 프로젝트 지침이 아니므로 dispatch와 Harness
step의 입력에 명시한다. 기본·상세 문서는 같은 Feature/revision과 evidence로 연결한다.
일반 Feature 작업에서 프로젝트 기준을 편집하지 않으며 공통 기준 변경은 별도 요청으로 다룬다.
**이유**: 기능 진행 정보가 공통 지침에 누적되거나 요약과 전문 계약이 서로 다른 원본이
되는 것을 방지한다.
**트레이드오프**: 문서 목록과 상대 링크를 관리해야 한다. 대신 원문 복제를 줄이고
upstream 변경의 영향과 stale evidence를 추적할 수 있다.
### ADR-026: Harness의 구성, Git 소유권과 검증 범위를 신뢰 경계로 관리한다
**상태**: 현재 [Harness skill](../.agents/skills/harness/SKILL.md)과
[프로젝트 지침](../AGENTS.md)의 실행 계약 기록. ADR-002의 구체적 실행 구성과
ADR-012의 운영 설명을 보완한다.
**결정**: 명령은 승인된 계획과 프로젝트 설정·preset·실제 metadata에 대조해 선택한다.
Config와 preset은 실행 가능한 입력이며 Hook이나 `shell=False`만으로 side effect가
격리되었다고 보지 않는다.
범위 밖 사용자 변경은 보존해야 하며, Executor는 branch·step 선택·timestamp·path-scoped
commit을 소유한다. 이 결정 당시 구현은 시작 전 clean 검사를 수행하고 비-phase 변경과
phase metadata를 분리했지만, Step의 소스·테스트 소유 경로를 커밋 시점에 검증하지 않았다.
해당 한계와 실패 분류·기록 보존의 후속 보완은 ADR-027을 따른다.
실행 중 동시 편집을 피하고 범위 밖 변경 발견 시 완료 대신 Coordinator로 반환한다.
Transport attempt는 최대 2회이며 구현이나 상위 계약 실패를
transport 문제로 반복하지 않는다. 권한 확대·원격·파괴 작업에는 명시적 승인이 필요하다.
PreToolUse의 파일 존재 검사는 RED evidence가 아니다. Stop의 문서 전용 생략은
유효한 동일 session/turn의 기록된 편집 대상이 모두 저장소 내부 Markdown인 조건에
한정된다. 기록 누락·손상이나 비문서 기록이면 정상 검증 경로를 따르며, shell 쓰기의
완전한 추적을 보장하지 않는다. 생략·미실행을 build/test 통과로 표시하지 않는다.
**이유**: 자동화가 관련 없는 변경을 commit하거나 검증 범위·권한을 과장하는 것을 방지한다.
**트레이드오프**: 실행 전 상태 검사와 명시적인 evidence가 필요하다. 문서 작업의 정적
검토와 production 변경의 필수 실행 검증을 구분하며, 오래된 운영 문서가 현재 계약을
덮어쓰지 않도록 실제 source와 대조한다.
### ADR-027: Harness의 Step 결과와 커밋 범위를 명시적 계약으로 검증한다
**상태**: 사용자 승인된 Harness 보완 계획(실패 상태 보존, 파일 소유권 검증, 환경 오류
분류)에 따른 결정. ADR-026의 실행 경계를 보완하며 solver·Hook·sandbox 권한을 변경하지 않는다.
**결정**: 프로세스 종료 코드와 Step 보고를 함께 판정한다. 명시적 `error/blocked`는
nonzero에서도 사유를 보존하고 자동 재시도하지 않는다. 인식된 sandbox helper 환경 오류는
종료 코드 0에서도 차단한다. 실제 wrapper timeout으로 결과가 미보고된 경우만 최초 포함
최대 두 번 시도하며, 단순 종료 코드 124나 미분류 nonzero를 transport로 추정하지 않는다.
Executor 소유 `attempt_history`는 원래 보고·프로세스 진단·판정을 재시도와 재개 때 보존한다.
Planning은 Step마다 정확한 상대 파일 목록 `owned_paths`를 작성한다. Executor는 신뢰된
목록으로 매 시도 후·stage 전·commit 전의 변경과 staged 경로를 검증하고 rename 양쪽
경로를 확인한다. 범위 위반 시 사용자 변경을 보존하고 재시도·커밋·다음 Step을 중단한다.
기존 완료 이력은 필드 없이 읽되 pending Step은 실행 전에 승인 목록을 보완해야 한다.
구체적인 schema와 복구 절차는 [Harness skill](../.agents/skills/harness/SKILL.md)과
[동작 과정](HARNESS_WORKFLOW.md)을 따른다.
**이유**: 실패를 재시도로 덮어쓰거나 실행 중 나타난 미승인 파일을 자동 커밋하는 일을 막는다.
**트레이드오프**: 실행할 기존 계획의 파일 목록을 준비해야 하고 실패 이력이 누적된다.
경로 검사는 filesystem sandbox나 동시 writer에 대한 원자적 격리가 아니다. 구현·metadata
커밋도 단일 transaction이 아니므로 뒤쪽 커밋 실패 시 앞선 커밋을 보존하고 오류로 반환한다.
## 후속 ADR 작성 기준
프로젝트 전체의 dependency 방향, 공통 identity·수명·결과 의미, 기술 baseline,
검증 정책 또는 agent 권한이 바뀌면 공통 ADR을 추가한다. 하나의 구현 항목에만
적용되는 선택은 Feature ADR에 기록한다.
각 결정에는 ID, 적용 범위, 상태, 결정, 이유, 트레이드오프, 근거와 영향받는 계약을 둔다.
기존 결정을 변경하면 명시적인 대체·보완 관계와 승인 근거를 남기며 과거 원문과 실패
evidence를 소급 수정하지 않는다. Feature 기록의 형식과 owner는
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다.