docs: organize project guidance and module contracts

This commit is contained in:
KOKO\Mimi
2026-09-29 00:34:57 +09:00
parent 73db138566
commit a3502c9b97
50 changed files with 1748 additions and 414 deletions
@@ -0,0 +1,24 @@
# 외부 입력 subset과 독립 솔버
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
기존 모델을 읽고 외부 결과로 검증해야 하지만, 공개 입력 형식과 외부 솔버의 내부 알고리즘은
같은 계약이 아니다. 파서 호환성을 제품 목표로 삼으면 검증 가능한 물리 의미보다 문법 수용이 앞설 수 있다.
## 결정
승인된 Abaqus keyword subset의 의미만 지원한다. S4/S4R 등 source 표기는 보존하고
FESA 정식화로 연결한다. 외부 solver의 내부 적분·안정화·상태·결과 생성 동등성은 주장하지 않는다.
## 대안과 선택 이유
Full compatibility는 비공개 내부 동작까지 추정해야 하므로 채택하지 않는다.
자체 입력 형식만 쓰는 방식은 기존 .inp와 외부 reference를 직접 활용하는 현재 작업 흐름과 맞지 않는다.
## 영향
입력과 kernel의 연결·차이를 명시해야 한다. Exact 수치 일치는 가능하지만 내부 동등성의
증거가 아니다. Unknown model-affecting 입력은 silent approximation 대신 실패한다.
@@ -0,0 +1,24 @@
# 검증 환경과 private backend
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
수치 library의 package target·integer·resource와 Windows runtime이 core로 퍼지면
물리 코드와 설치 환경을 독립적으로 검증하기 어렵다.
## 결정
현재 CMake/MSVC x64 Debug/CTest와 C++17 이상을 검증 기준으로 유지한다. MKL·TBB·
HDF5·Win32는 backend-neutral 경계 뒤에 두고 project-owned dependency target과 runtime staging을 사용한다.
## 대안과 선택 이유
Vendor 타입을 public에 노출하면 adapter 교체가 core와 consumer 변경으로 전파된다.
다른 toolchain의 즉시 지원 선언은 해당 환경의 numerical/runtime evidence 없이 할 수 없다.
## 영향
Dependency 추가마다 build뿐 아니라 실제 runtime closure를 확인한다. 개인 설치 경로를
제품 계약으로 고정하지 않으며 실행기 MSBuild 지원을 FESA의 별도 제품 검증으로 취급하지 않는다.
@@ -0,0 +1,24 @@
# 모델 정의와 equation 소유권
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
Source label, 모델 배열과 equation 번호는 서로 다른 수명과 의미를 가진다. 실행별
제약이나 procedure가 바뀌어도 원본 모델과 결과 identity는 보존되어야 한다.
## 결정
Domain이 전체 정의를 소유하고 AnalysisModel은 non-owning view로 둔다.
DofManager가 DOF·partition·equation·sparse pattern을 전담한다. Semantic definition과 numerical object는 검증된 생성 경계로 연결한다.
## 대안과 선택 이유
Node/Element에 equation 번호를 저장하면 여러 실행 상태가 원본 정의에 섞인다.
모델 복사는 별도 수명·동기화 비용을 만들고 source identity가 다른 복사본처럼 취급될 수 있다.
## 영향
Domain 수명을 view보다 길게 유지해야 한다. Parser나 consumer가 모든 concrete storage를
알아야 하는 구조를 피하되 speculative clone·registry·사용하지 않는 capability는 추가하지 않는다.
@@ -0,0 +1,24 @@
# Local contribution과 결정적인 조립
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
병렬 계산의 속도를 얻으면서 같은 입력의 sparse 구조·합산·진단·결과 순서를
재현해야 한다. Floating-point 누적 순서는 수치 결과에 영향을 준다.
## 결정
Local contribution은 index-owned buffer에 계산하고 join 뒤 stable COO와 고정된
reduction으로 global matrix/vector에 반영한다. Global pattern은 DOF owner가 정의한다.
## 대안과 선택 이유
Worker의 직접 global CSR 갱신은 race 또는 lock 순서 의존을 만든다.
Hash iteration에 의존한 누적도 stable source ordering을 보장하지 않는다.
## 영향
Contribution buffer와 정렬 비용을 부담한다. Optimization은 같은 순서·물리 의미·실패
선택을 보존해야 하며 더 빠르다는 이유로 결정론을 선택 기능으로 만들 수 없다.
@@ -0,0 +1,24 @@
# Candidate 검증과 공식 HDF5
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
반복 중 일부 값 또는 저장 중 일부 dataset만 성공한 결과를 정상 해석으로 읽으면
실패 뒤 기존 유효 결과까지 신뢰할 수 없게 된다.
## 결정
State와 recovery는 완성·검증된 candidate만 반영한다. 공식 결과는 입력 lexical sibling의
HDF5이며 임시 파일의 self-check·close 후 최종 교체한다. Output lease로 동일 output pair의 동시 쓰기를 막는다.
## 대안과 선택 이유
실패 중간 state나 final 파일에 직접 누적하면 rollback 범위를 명확히 하기 어렵다.
CSV를 공식 결과로 두면 계층적 위치·단위·identity 계약을 현재 방식으로 유지할 수 없다.
## 영향
Candidate와 readback 비용을 부담한다. State commit과 file finalize, final HDF5와
진단 로그의 수명은 구분하며 실패 시 로그까지 동일하게 보존된다고 약속하지 않는다.
@@ -0,0 +1,24 @@
# Procedure별 lifecycle과 full residual
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
정적·비선형·고유치·동적 해석은 초기화·해법·종료·결과 의미가 다르다.
반력과 free 잔차는 같은 수치 vector에 있어도 다른 물리적 역할을 가진다.
## 결정
각 procedure가 필요한 state와 solver lifecycle을 소유한다. 기존 선형 정적 해석은
elimination의 coupling을 유지하고 full residual Kd-F에서 constrained 반력과 free 평형을 구한다.
## 대안과 선택 이유
Static lifecycle에 계속 분기를 누적하면 다른 procedure의 state·종료 의미가 섞인다.
Constrained 외력만 부호 반전한 반력은 지정 변위와 stiffness coupling을 반영하지 못한다.
## 영향
새 procedure는 입력부터 output까지 연결해야 한다. 빈 free system은 유효한 경우
지원하며 arbitrary penalty·regularization을 failure의 우회로로 사용하지 않는다.
@@ -0,0 +1,24 @@
# 원본 reference와 승인된 비교 정책
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
구현에 맞춰 기준 데이터를 고치거나 family마다 scale을 달리 정하면 수치 검증이
구현과 기준의 순환적 자기 정당화가 된다.
## 결정
기존 reference의 경로·값을 보존하고 source identity·component를 먼저 일대일
대응한다. Approved family/scale/near-zero/row/RMS/zero-scale 정책과 판정 영향을 유지한다.
## 대안과 선택 이유
Canonical naming·보조 metadata를 필수로 추가하는 방식은 실제 비교에 필요하지 않은
정리 작업을 gate로 만든다. Missing row 무시·평균·floor·clamp는 다른 모델을 통과시킬 수 있다.
## 영향
필수 원본이 없으면 비교 미실행으로 남긴다. 정책 변경은 사용자 승인과 영향 검증을
요구하며 새 evidence를 생성할 수 있지만 과거 실패 보고와 원본을 소급 수정하지 않는다.
@@ -0,0 +1,24 @@
# 수치·물리·외부 비교의 분리
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
유한한 해, 선형계 성공 또는 외부 변위 일치만으로 정식화·회복·에너지·시간 정확성을
모두 확인할 수 없다. HHT의 reference 통과와 temporal 실패도 별개 증거다.
## 결정
동작 검사, analytical/invariant, 필요한 reference와 독립 numerical/physics 판단을
구분한다. 수식·요소·재료·적분·상태 갱신 변경은 독립 검토를 받는다.
## 대안과 선택 이유
모든 기능에 같은 고정 benchmark 목록을 강제하면 의미 없는 검사를 늘린다.
반대로 test count나 runner exit만으로 완료를 판정하면 검증되지 않은 물리를 통과로 오인한다.
## 영향
기능별 필수 evidence와 미실행·실패·제외를 명시해야 한다. Release-readiness 감사는
별도 요청이며 독립 검토·감사 결과가 배포 권한을 부여하지 않는다.
@@ -0,0 +1,24 @@
# 필요한 전문 작업과 명시적 검증 실행
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
고정 stage·반복 인계·자동 Git·종료 hook 중심 운영은 실질적인 공학 판단보다
형식적인 상태 유지와 중복 실행을 늘렸다.
## 결정
메인이 범위를 파악해 필요한 전문 작업만 배정한다. 실행기는 config·toolchain·
backend 명령을 명시 호출 시 한 번 실행한다. 일반 실패는 현재 owner가 수정한다.
## 대안과 선택 이유
전용 coordinator·planning/correction profile·고정 상태기계·retry 예산을 유지하는
방식은 폐기한다. 검증 script에 commit/push 권한을 묶는 방식도 채택하지 않는다.
## 영향
메인이 작업 범위와 evidence를 확인해야 한다. 반복 승인 없이 승인된 일반 작업을
이어가되 원격·파괴·외부 비용·상위 계약 변경의 사용자 결정 경계는 유지한다.
@@ -0,0 +1,24 @@
# 공통 기준과 기능별 상세 계약
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
공통 기준에 모든 기능 진행상태를 누적하거나 같은 checklist를 여러 파일에 두면
어느 기록이 현재 요구와 상태인지 모호해진다.
## 결정
공통 제품·수치 기준과 기능별 요구·정식화·I/O·결정을 구별한다. Feature의
FEATURED_AGENTS·PRD·ADR을 유지하고 현재 checklist는 Feature PRD 한 곳에 둔다.
## 대안과 선택 이유
모든 기능에 빈 보고서·requirements·matrix를 일괄 만드는 방식은 중복을 늘린다.
기존 계약을 새 파일명 규칙에 맞춰 자동 이동·재번호화하면 승인·evidence의 추적성을 잃는다.
## 영향
복잡한 상세 내용만 분리한다. 기존 ID·승인 근거·reference와 과거 운영 이력을 보존한다.
전체 상태 요약이 기능별 필수 검사를 대체하지 않으며 공통 기준 변경은 별도 요청으로 다룬다.
@@ -0,0 +1,24 @@
# MITC4 고유치 첫 구현의 경계
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
MITC4 고유치의 첫 구현에서 외부 값 차이와 추가 정확도 개선을 분리해 진행할
필요가 있었고, 사용자가 모드별 5% 범위의 첫 구현을 승인했다.
## 결정
실제 FEAST와 consistent에서 유도한 lumped mass를 사용한다. 외부 Value는 mode별
singleton family의 상대오차·RMS 모두 5%로 판정하는 named policy를 적용한다.
## 대안과 선택 이유
공통 RMS 1%를 이 첫 구현에 그대로 요구하는 선택 대신 범위를 명시한 예외를
채택했다. 다른 모드의 scale로 차이를 흡수하거나 reference를 보정하는 방식은 허용하지 않는다.
## 영향
다른 해석의 RMS 1%와 내부 eigen 잔차·정규화·직교성 기준은 유지한다.
정확도 개선·보류한 검증은 해결된 것으로 취급하지 않고 과거 1% 실패 기록도 보존한다.
@@ -0,0 +1,24 @@
# HHT의 consistent kinetic mass
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
유한회전 shell 동역학에서는 회전관성과 configuration에 따른 kinetic kinematics를
다뤄야 한다. 고유치 계산의 질량 선택을 그대로 옮기면 다른 물리를 해석할 수 있다.
## 결정
HHT에는 사용자 선택인 consistent kinetic mass를 사용하고 analytic null·
부분구속·회전 관성·convective 항을 보존한다. 물리 가속도와 알고리즘 보조 가속도를 구분한다.
## 대안과 선택 이유
Lumped mass는 비교 연구로 남겼으며 현 HHT 지원의 fallback으로 채택하지 않았다.
임의 drilling inertia나 부분구속의 full-clamp 치환은 원래 모델을 바꾼다.
## 영향
비대칭 접선·moving null·regularity와 실제 shell temporal 검증 부담이 있다.
현재 시간수렴 실패를 유지하며 가속도 복구 후보는 독립 검증·채택 전 승인된 해법으로 간주하지 않는다.
@@ -0,0 +1,24 @@
# Uncoupled shell 열해석부터 구현
- 상태: 기존 승인·인터뷰 합의의 의미 유지
- 결정 주체: 사용자와 기존 승인 계약의 담당자
## 배경
최종 목표는 양방향 열-구조 연성이지만, 현재는 온도장 자체의 transient 해석과
검증 범위를 먼저 확정해야 한다.
## 결정
첫 범위는 단일 step uncoupled shell 열해석, 균질 단면의 온도점 5개와 상수 물성,
고정 증분이다. 초기에 검토한 두께 방향 등온 범위는 5점 온도장으로 대체한다.
## 대안과 선택 이유
즉시 양방향 연성을 구현하는 방식은 현재 요구 범위를 넘는다. 두께 등온 모델은
아랫면·윗면의 독립 지정 온도와 두께 방향 열전달 요구를 충족하지 못한다.
## 영향
열행렬·flux·반력·에너지·시간수렴을 별도로 검증해야 한다. 두 구간 이차 보간,
Backward Euler, geometry 근사와 결과 schema는 제안 상태이며 이 범위 결정만으로 채택되지 않는다.
+20
View File
@@ -0,0 +1,20 @@
# 프로젝트 결정 목록
현재 유지하는 선택과 그 비용을 구분한다. 과거 승인 이력과 수치 기준은 그대로 보존하며,
아래 기록은 새로운 physics·acceptance 승인이 아니다. 열해석의 제안 방법은 채택 목록에 넣지 않는다.
| 파일 | 유지하는 선택 |
| --- | --- |
| `0001-independent-solver.md` | 외부 입력 subset과 독립 솔버 |
| `0002-build-and-backends.md` | 검증 환경과 private backend |
| `0003-model-and-equations.md` | 모델 정의와 equation 소유권 |
| `0004-ordered-assembly.md` | Local contribution과 결정적인 조립 |
| `0005-state-and-output.md` | Candidate 검증과 공식 HDF5 |
| `0006-procedure-lifecycle.md` | Procedure별 lifecycle과 full residual |
| `0007-reference-evidence.md` | 원본 reference와 승인된 비교 정책 |
| `0008-layered-verification.md` | 수치·물리·외부 비교의 분리 |
| `0009-explicit-development.md` | 필요한 전문 작업과 명시적 검증 실행 |
| `0010-feature-contract-ownership.md` | 공통 기준과 기능별 상세 계약 |
| `0011-eigen-first-implementation.md` | MITC4 고유치 첫 구현의 경계 |
| `0012-hht-kinetic-mass.md` | HHT의 consistent kinetic mass |
| `0013-thermal-staged-scope.md` | Uncoupled shell 열해석부터 구현 |
+47
View File
@@ -0,0 +1,47 @@
# 미해결 문제
## HHT shell의 시간수렴
- 조건·현상: 실제 shell의 두 시간수렴 사례에서 요구한 수렴 성능을 만족하지 못한
재현 기록이 남아 있다. 원본 변위 reference 통과와 함께 존재하는 실패다.
- 영향: 변위 일치만으로 동적 가속도·관성·에너지·전체 시간 정확성을 보장할 수 없다.
HHT 전체 기능 완료를 선언할 수 없다.
- 현재 해결하지 않는 이유: 문서 재구성 범위를 벗어나는 수치 알고리즘 변경이며,
가속도 복구 후보의 정식화·독립 검증·채택 판단이 선행되어야 한다.
- 후속 방향: 기존 물리 질량·허용 오차를 유지한 재현에서 dt refinement별 q/v/물리 a와
hidden constraint 차수를 분리하고 후보 변경의 영향을 검증한다.
## Python 운영 계약 검사의 기대값 불일치
- 조건·현상: `tests/test_agent_skill_workflow_contract.py`의 inventory 검사는 11개
profile을 기대하지만 현재 `.codex/agents`에는 7개가 있다. 같은 파일은 루트 지침의
고정 단계 표를 parsing하고, 과거 phase 실행 예제를 검사한다. 현재 명시 실행기와
필요한 전문 작업만 호출하는 운영 원칙에 맞지 않는다.
- 영향: 이 검사를 현행 운영의 통과 증거로 쓰거나 통과시키기 위해 삭제된 절차를
복원하면 잘못된 개발 흐름을 다시 도입한다. 루트 문서 재구성 이후에는 옛 표 위치에
의존하는 검사도 조정 대상이다.
- 현재 해결하지 않는 이유: 기존 불일치는 source 정적 대조로 확인했지만 이번 요청은
문서 변경이다. Python 검사를 실행하거나 테스트 코드를 수정하지 않았다.
- 후속 방향: 유효한 동작·권한·검증 범위를 검사하도록 기대값을 정리하고 Python suite를
별도로 실행한다. 현재 CTest의 성공으로 대체하지 않는다.
## 열 reference의 작업 사본 내 부재
- 조건·현상: 열해석 계획은 기존 `shell-thermal.inp`와 `shell-thermal NodalTemperature.csv`를
지정하지만 이 작업 사본의 `reference/shell-thermal`에는 해당 파일이 없다. 앞선 계획
작업에서는 별도 기존 저장소의 원본을 읽기 전용으로 확인했다.
- 영향: 이 작업 사본만으로 열 reference 비교를 재현할 수 없다. CSV는 t=37의 NT11
한 frame만 포함하므로 원본 확보 뒤에도 flux·반력·두께 온도 분포의 검증을 대신하지 않는다.
- 현재 해결하지 않는 이유: Reference 생성·복원·복사는 현재 요청에 포함되지 않는다.
명명 규칙 때문에 새 artifact나 보조 metadata를 만들지 않는다.
- 후속 방향: 실제 비교 작업 시 사용할 기존 원본 경로를 명시하고 허용된 접근으로
읽는다. 보존된 원본의 행·identity·값을 수정하지 않는다.
## 외부 배포 결정의 공백
- 조건·현상: 외부 사용자 배포는 장기 목표지만 배포 형태·지원 환경·dependency 재배포
조건과 외부 입력의 신뢰 범위는 정해져 있지 않다. 사용자가 별도 보안 정책은 없다고 확인했다.
- 영향: 현재 로컬 실행·개인 연구 범위를 외부 서비스의 보안·설치·지원 보장으로 설명할 수 없다.
- 현재 해결하지 않는 이유: 제품 배포 범위와 권리 검토는 아직 요청되지 않았으며 코드만으로
사용자의 배포 방식을 정할 수 없다.
- 후속 방향: 배포를 실제 추진할 때 형식·대상·설치·검증·데이터 취급 조건을 구체화한다.
+40
View File
@@ -0,0 +1,40 @@
# 개발 현황
기준일은 2026-09-28이다. 현재 주목적은 개인 연구용 솔버 개발이며 외부 사용자 배포는
장기 목표다. 아래 검증 상태는 기존 실행 기록의 범위이며 이번 문서 작업에서 solver나
검증 suite를 새로 실행한 결과가 아니다.
## 구현과 검증 상태
| 영역 | 구현 상태 | 확인된 evidence와 한계 |
| --- | --- | --- |
| Abaqus 입력·Domain·source identity | 구현됨 | Reader/mapper/invalid input 테스트가 존재. 최신 전체 suite 통과를 새로 주장하지 않음 |
| B33·MITC4 선형 정적 | 구현됨 | Local·integration·reference 검사가 존재. 과거 readiness는 이후 기준 변경으로 재검증 대기 표시가 있으므로 현재 release 통과로 승계하지 않음 |
| MITC4 비선형 정적·표면 압력 | 구현됨 | Newton·pressure tangent·result/reference 관련 검사와 실행 기록이 있음. 현 checkout 전체 재검증 없음 |
| MITC4 frequency | 승인된 첫 구현 완료 기록 | 당시 전체 417개 검사와 모드별 외부 Value 5% 비교·독립 검토 통과. 추가 검증 S3와 정확도 향상은 보류 |
| HHT 동해석 | 입력부터 HDF5까지 구현, 기능 검증 미완료 | 101-frame U 비교 PASS 기록, UR 경고 200건. Shell 시간수렴 두 사례 실패와 잔여 physics coverage 유지 |
| HHT 굽힘 단면력 복구 | 두께 계수 수정됨 | 관련 Debug 14 tests와 원본 HDF5 재생성·독립 식 대조 완료 기록. 전체 동해석 완료와 별개 |
| HHT 관련 전체 CTest | 일부 실패·미실행 범위 존재 | 최근 기록은 두 시간수렴 검사를 제외한 475 PASS/1 SKIP. 제외한 검사를 통과로 계산하지 않음 |
| Shell transient heat transfer | 요구사항·상세 수치 계획 작성, solver 미구현 | 5개 온도점·uncoupled 범위 합의. 수식 검산은 제한된 algebra evidence이며 solver/reference 통과 아님 |
| Python 검증 실행기 | 구현됨 | 명시 build/test runner와 별도 Python suite가 존재. 일부 운영 계약 검사는 현행 절차와 맞지 않는 기대값을 유지 |
| 외부 사용자 배포 | 계획 | 배포 방식·설치·지원 정책과 dependency 재배포 검토가 아직 정해지지 않음 |
## 남은 작업과 의존성
1. Shell 열해석은 geometry·두께 station 접속·시간 종료 규칙·초기 온도 jump·edge 입력·
결과 schema를 확정한다. 채택된 정식화의 독립 검토 이후 semantic mapping, DOF,
행렬·시간 적분·recovery·HDF5와 검증을 연결한다. 단일 시점 NT11 비교 외 물리 검증을
별도로 마련해야 한다. 현재 진행 요청에 가장 가까운 구현 준비 작업이다.
2. HHT는 기존 시간수렴 실패를 유지한 상태에서 물리 가속도 복구 후보의 정식화·독립
검증·채택 여부를 결정한다. 강체 병진 전체 이력, Newton 경계·실패 보존, 반복 결정론,
partition·좌표변환 coverage를 완료하고 필수 전체 검사를 다시 수행해야 한다.
3. Python 운영 계약 검사는 폐기된 profile·고정 단계·phase 인자 기대값을 현행 명시
실행 절차에 맞게 정리하는 별도 작업이 필요하다. 현재 문서 수정에 테스트 코드 변경을
포함하지 않는다.
4. Eigen 첫 구현 이후 정확도 개선과 보류한 검증을 별도 범위로 정한다. 현재 승인된
5% 기준을 다른 해석으로 확대하거나 과거 실패 기록을 수정하지 않는다.
5. 이후 양방향 열-구조 연성과 외부 사용자 배포의 구체적인 요구·지원 범위를 정한다.
두 장기 목표 간 순서나 일정은 정해지지 않았다.
각 기능의 세부 checklist와 승인 이력은 기존 기능 단위로 유지한다. 전체 요약의 상태가
상세 계약·필수 검사·실패 기록을 대체하지 않는다.