add docu

docs/ADR.md

@@ -1,41 +1,69 @@
 # Architecture Decision Records
 
 ## 철학
-Harness는 현재 프로젝트의 실제 기술 스택을 반영해야 한다. C++/MSVC 프로젝트에서 npm, Next.js, TypeScript test naming을 기본값으로 두면 agent prompt와 hook policy가 잘못된 구현을 유도한다.
+Abaqus User Subroutine 개발은 일반 application code 개발보다 ABI, solver execution, compiler integration, reference artifact provenance의 영향을 크게 받는다. 이 프로젝트의 결정은 Abaqus 실행을 기본 전제로 삼지 않으면서도, Fortran code와 numerical behavior를 검증 가능한 단위로 나누는 방향을 따른다.
 
 ---
 
-### ADR-001: C++ 전용 Harness
-**결정**: Harness scaffold는 C++/MSVC 전용으로 운영한다. JavaScript/TypeScript fallback은 유지하지 않는다.
+### ADR-001: 프로젝트 정체성은 Abaqus User Subroutine Development다
+**결정**: 이 저장소의 프로젝트 정체성은 Abaqus User Subroutine development로 둔다. 다른 개발 체계를 프로젝트 정체성으로 사용하지 않는다.
 
-**이유**: FESA 개발 환경은 MSVC 기반 C++이다. 언어별 fallback을 남기면 validation, TDD guard, acceptance criteria가 흐려진다.
+**이유**: 현재 agent, skill, research, validation script는 Abaqus User Subroutine 개발 workflow를 중심으로 확장되어 있다. 프로젝트 이름과 문서가 다른 정체성을 말하면 agent가 잘못된 우선순위와 검증 경로를 선택한다.
 
-**트레이드오프**: 같은 Harness scaffold를 JS/TS 프로젝트에 재사용할 수 없다. 필요하면 별도 template이나 language registry를 새 ADR로 설계한다.
+**트레이드오프**: 기존 script와 environment variable 이름에 남아 있는 `HARNESS_*` prefix는 호환성을 위해 유지한다. 이름은 historical implementation detail로 취급하고, 문서의 목적 설명은 Abaqus User Subroutine 개발에 맞춘다.
 
-### ADR-002: CMake/MSVC/x64/Debug 기본 검증
-**결정**: 기본 workspace validation은 CMake, Visual Studio 17 2022 generator, x64 platform, Debug config, CTest로 수행한다.
+### ADR-002: Fortran과 Intel oneAPI를 기본 구현 체계로 사용한다
+**결정**: Abaqus User Subroutine production source는 Fortran을 기본 언어로 작성하고, Intel oneAPI Fortran compiler를 기본 compiler family로 사용한다. 자동 탐지는 `ifx`를 우선하고 `ifort`를 fallback으로 둔다.
 
-**이유**: MSVC 환경에서 CMake/CTest는 source tree가 복원되거나 새 C++ project가 추가될 때 가장 일관된 build/test entry point다.
+**이유**: Abaqus User Subroutine의 일반적인 Windows workflow는 Fortran compiler와 Abaqus execution procedure의 연동에 의존한다. `ifx` 우선 정책은 oneAPI 현재 방향과 맞고, `ifort` fallback은 기존 Abaqus 환경과의 호환성을 보존한다.
 
-**트레이드오프**: Visual Studio solution-only project는 기본 지원하지 않는다. 명시적으로 필요하면 `HARNESS_VALIDATION_COMMANDS`로 override한다.
+**트레이드오프**: C/C++ subroutine workflow는 기본 지원 범위가 아니다. 필요하면 별도 feature requirement와 interface contract에서 명시한다.
 
-### ADR-003: 엄격한 C++ TDD Guard
-**결정**: C++ production file 변경은 관련 C++ test file이 없으면 차단한다.
+### ADR-003: 개발은 7단계 gate workflow로 진행한다
+**결정**: 모든 중요한 subroutine feature는 requirements, research, formulation, interface, test model, implementation, validation gate를 통과한다.
 
-**이유**: Harness의 핵심 목적은 agent가 검증 없는 C++ 변경을 만들지 않도록 하는 것이다. Header 중심 C++ 구조에서도 module 또는 basename 기반 테스트 존재를 확인한다.
+**이유**: Abaqus User Subroutine은 수학, ABI, input deck, compiler, solver output이 동시에 맞아야 한다. Agent가 한 단계에서 모든 결정을 내리면 검증 불가능한 구현이 만들어질 위험이 크다.
 
-**트레이드오프**: 초기 scaffolding 작업에서 guard가 엄격하게 느껴질 수 있다. 문서, CMake 설정, Harness metadata는 guard 대상에서 제외한다.
+**트레이드오프**: 작은 변경에도 문서화 비용이 생긴다. 단, 단순 correction은 기존 approved contract 안에서 Correction Agent가 최소 수정으로 처리할 수 있다.
 
-### ADR-004: Harness 자체 테스트 우선
-**결정**: commit hook은 먼저 Python Harness self-test를 실행한 뒤 workspace validation을 실행한다.
+### ADR-004: 기본 검증은 no-Abaqus path로 유지한다
+**결정**: `python scripts/validate_workspace.py`는 기본 검증 entry point이며 Abaqus job을 자동 실행하지 않는다. Abaqus 실행은 `HARNESS_ABAQUS_VALIDATION=run`과 `HARNESS_ABAQUS_VALIDATION_COMMANDS`가 명시된 경우에만 수행한다.
 
-**이유**: 현재 저장소에는 C++ source tree가 없을 수 있다. Harness가 스스로 검증 가능해야 이후 phase generation과 source restoration을 안전하게 진행할 수 있다.
+**이유**: Abaqus 실행은 설치, 라이선스, target version, compiler integration, working directory, scratch behavior에 의존한다. 기본 검증이 Abaqus에 의존하면 개발 재현성이 떨어진다.
 
-**트레이드오프**: commit 시간이 조금 늘어난다. 대신 hook/validation regressions를 빠르게 잡는다.
+**트레이드오프**: 기본 검증만으로 Abaqus runtime symbol resolution이나 actual solver behavior를 완전히 보장할 수 없다. 해당 evidence는 opt-in validation과 approved reference artifacts로 보완한다.
 
-### ADR-005: Fortran Abaqus UserSubroutine 확장
-**결정**: Abaqus UserSubroutine 구현 언어는 Fortran으로 둔다. 기본 validation은 no-Abaqus mode를 유지하고, Intel oneAPI Fortran kernel/fake-driver tests와 reference artifact metadata validation을 수행한다.
+### ADR-005: Abaqus ABI wrapper는 얇게 유지하고 계산 kernel은 no-Abaqus로 검증한다
+**결정**: Subroutine source는 가능한 한 thin Abaqus ABI wrapper와 testable kernel 또는 driver logic으로 분리한다.
 
-**이유**: Abaqus UserSubroutine은 Abaqus runtime, license, compiler integration에 의존한다. 기본 hook이나 workspace validation에서 Abaqus job을 자동 실행하면 개발 환경과 license 상태에 따라 재현성이 떨어진다. 계산 kernel과 Abaqus ABI wrapper를 분리하면 no-Abaqus 환경에서도 TDD를 유지할 수 있다.
+**이유**: UMAT, VUMAT, UEL 같은 entry point는 Abaqus가 호출하는 argument contract가 크고 solver-dependent하다. 핵심 계산 로직을 no-Abaqus test에서 검증할 수 있어야 RED -> GREEN -> VERIFY 개발이 가능하다.
 
-**트레이드오프**: no-Abaqus validation은 Abaqus symbol resolution, include compatibility, actual job execution을 완전히 보장하지 않는다. 해당 검증은 `HARNESS_ABAQUS_VALIDATION=run`으로 명시한 환경에서만 수행한다.
+**트레이드오프**: Wrapper와 kernel 사이의 mapping code가 추가된다. 이 mapping 자체는 interface contract와 wrapper-level compile/smoke test로 검증해야 한다.
+
+### ADR-006: Reference artifacts는 metadata contract로 검증한다
+**결정**: Abaqus reference artifacts는 `references/<feature-id>/<model-id>/metadata.json`과 함께 보관하고, `scripts/validate_reference_artifacts.py`로 metadata, source hash, required files를 검증한다.
+
+**이유**: Abaqus output CSV만 있으면 어떤 source, Abaqus version, compiler, precision, command에서 생성됐는지 추적할 수 없다. Source hash와 log tail을 포함해야 comparison evidence로 사용할 수 있다.
+
+**트레이드오프**: Reference artifact 준비 비용이 증가한다. 대신 stale artifact, source mismatch, missing provenance를 자동으로 탐지할 수 있다.
+
+### ADR-007: Fortran production 변경은 TDD guard 대상이다
+**결정**: `.f`, `.for`, `.f90`, `.f95`, `.f03`, `.f08` production source 변경은 관련 test file이 없으면 guard가 차단한다.
+
+**이유**: Abaqus User Subroutine 구현은 numerical regression을 만들기 쉽다. Production code 변경 전에 no-Abaqus driver test 또는 관련 existing test를 확보해야 한다.
+
+**트레이드오프**: 초기 prototype 작성 시 guard가 엄격하게 느껴질 수 있다. 이 경우에도 먼저 minimal driver test를 두고 구현한다. Reference artifacts와 documentation은 production-source guard 대상에서 제외한다.
+
+### ADR-008: Optional CMake/MSVC validation은 supporting path로만 유지한다
+**결정**: CMake project가 존재하면 Visual Studio 17 2022, x64, Debug, CTest validation path를 실행한다. 단, 이것은 supporting native components를 위한 optional path이며 프로젝트 정체성을 바꾸지 않는다.
+
+**이유**: 기존 validation infrastructure가 CMake/CTest를 지원하고, 향후 helper library나 supporting native code가 생길 수 있다. 하지만 Abaqus User Subroutine development의 기본 구현 단위는 Fortran과 Abaqus ABI contract다.
+
+**트레이드오프**: 문서에서 CMake/MSVC를 완전히 제거하지 않는다. 대신 optional supporting validation으로 제한해 agent가 C++ project로 오해하지 않게 한다.
+
+### ADR-009: Public examples는 acceptance evidence가 아니다
+**결정**: Public Abaqus subroutine repositories, course notes, blogs는 layout과 learning reference로만 사용한다. Acceptance evidence가 되려면 source reliability, license, version, applicability, generated artifact provenance를 별도로 기록해야 한다.
+
+**이유**: Public example은 bug-free 또는 validation-quality artifact라는 보장이 없다. 이 프로젝트의 acceptance는 requirements, reference artifact metadata, comparison evidence, physics sanity를 통해 판단한다.
+
+**트레이드오프**: 공개 예제를 빠르게 복사해 시작하는 방식보다 느리다. 대신 장기적으로 source provenance와 verification traceability를 유지할 수 있다.