FESADev/docs/mitc4-shell-feast-eigen/ADR.md

# MITC4 Shell Mass Matrix와 FEAST 고유치해석 결정 기록

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `coordinator-agent`
- Input contract revision: `r2`

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md), [프로젝트 ADR](../ADR.md),
[SOLVER_AGENT_DESIGN](../SOLVER_AGENT_DESIGN.md).
문서 목록은 [FEATURED_AGENTS.md](FEATURED_AGENTS.md), 상태 원본은 [coordination.md](coordination.md)에 있다.

## MFE-ADR-001 — 사용자 지정 backend와 reference 범위

- 상태: 사용자 요청으로 확정된 intake 범위.
- 결정 owner: user; 기록 owner: coordinator-agent.
- 결정: MITC4 질량행렬 및 고유치해석을 구현하고 고유치 계산에는 MKL FEAST를 사용한다. 지정된 `reference/shellNL-eigen-meshfine` reference에서 외부 비교는 고유치만 수행한다.
- 근거: 2026-09-06 사용자 요청; [Feature PRD 사용자 요구](PRD.md#사용자-요구).
- 영향: backend 대체, 외부 mode-shape acceptance 추가 또는 reference 변경으로 요구를 우회하지 않는다.

## MFE-ADR-002 — MITC4 질량 이산화

- 상태: 사용자 후속 요구로 확정됨; 상세 lumping 수식은 Research/Formulation 소유.
- 결정 owner: user; 선택지 검토 owner: requirement-agent; 상세 수식 owner: formulation-agent.
- 결정: `consistent mass`를 계산하고 이를 이용하여 `lumped mass`도 계산한다. 앞서 제안한 둘 중 하나의 선택이 아니라 두 계산의 연결이 사용자 요구이다.
- 근거: 2026-09-06 사용자 후속 답변 “mass matrix는 consistent mass를 계산하고 이를 이용해서 lumped mass를 계산합니다.”; [원래 질문 evidence](requirements-evidence.md#중요한-결정).
- 영향: Requirement owner는 r1에서 두 계산과 관계를 baseline에 반영한다. 실제 FEAST 질량은 후속 명시 답변으로 lumped로 확정되었으며 MFE-ADR-004를 따른다.
- 경계: 기존 비물리 drilling DOF에 인공 관성을 추가하지 않는 방향을 권고한다. FEAST generalized problem의 mass SPD 조건과 질량 없는 drilling 처리는 Research와 Formulation이 물리 spectrum 보존 근거를 제시해야 한다. 축소 수식은 이 관리문서에서 정하지 않는다.

해석 기준 상태, backend 입력 관례 및 additive 결과량은 Requirement owner의 reference와 기존 계약 evidence로 정리한다.
새로 밝혀지는 비호환 영속 계약 또는 다른 critical 선택이 있으면 별도 근거와 함께 기록한다.

## MFE-ADR-003 — Local 검증 경로와 점진적 커밋

- 상태: 사용자 요청으로 승인됨.
- 결정 owner: user; 기록 owner: coordinator-agent.
- 결정: `FESA_GTEST_SOURCE_DIR`는 `C:\git\googletest`를 사용한다. 사용자 수정 `AGENTS.md`를 커밋하고 이후 작업도 Git에 점진적으로 커밋한다.
- 근거: 2026-09-06 사용자 후속 답변; Root가 해당 GoogleTest `CMakeLists.txt` 존재를 확인했다.
- 영향: Root는 사용자 수정 `AGENTS.md`와 완료된 upstream 문서의 정확한 경로 checkpoint를 커밋한다. 구현 단계 branch·step 선택·source/phase 커밋은 기존 Harness Executor 소유를 유지한다. Remote 작업 승인은 포함하지 않는다.

## MFE-ADR-004 — FEAST에 사용하는 질량행렬

- 상태: 사용자 명시 답변으로 승인됨.
- 결정 owner: user; 대안·영향 owner: requirement-agent.
- 결정: `consistent mass -> lumped mass -> 고유치 해석` 순서로 수행하고 FEAST/reference baseline의 `M`은 derived lumped mass를 사용한다. Consistent는 lumping 원본과 내부 질량 검증 대상으로 유지한다.
- 이유와 영향: 사용자가 최종 계산 흐름과 해석 사용 질량을 직접 명시했다. Modal residual, normalization 및 orthogonality의 기준 `M`도 실제 사용한 lumped mass이다.
- 근거: 2026-09-06 사용자 답변 “고유치 해석에서는 lumped mass를 사용합니다. 따라서 고유치 해석을 할 때 consistent mass -> lumped mass -> 고유치 해석 입니다”; [Requirement owner r1 결정 evidence](requirements-evidence.md#중요한-결정)의 `MFE-OQ-002`를 해소한다.
- 경계: 두 mass variant 외부 비교 또는 사용자 선택 API를 추가 요구하지 않는다. Lumping 수식은 Research/Formulation이 계약과 evidence로 구체화한다.

## MFE-ADR-005 — 요청 고유치 개수의 입력 권위

- 상태: 사용자 명시 확인; 기존 r1 요구사항의 의미 유지.
- 결정 owner: user; 기록 owner: coordinator-agent.
- 결정: 고유치 개수는 `.inp`의 `*FREQUENCY` data를 사용한다. 지정 input의 요청은 `10`개이며 reference 행수나 FEAST 내부 count 추정으로 요청 개수를 역추론하지 않는다.
- 근거: 2026-09-06 사용자 답변 “inp 파일의 고유치 개수를 사용합니다”; [r1 FEM-REQ-MITC4-EIGEN-009/015](requirements.md#requirement-verification-matrix).
- 영향: 기존 mode-count 의미의 확인이므로 contract revision은 `r1`을 유지한다. FEAST interval/subspace는 입력 요청의 낮은 N개와 multiplicity·누락 검증을 충족하기 위한 내부 처리이다. 새 입력 설정 기능을 추가하지 않는다.

## MFE-ADR-006 — 질량 lumping과 질량 없는 좌표의 정식화

- 상태: Formulation owner 수학 계약 및 r2 독립 Numerical Review gate 확인.
- 결정 owner: formulation-agent; 기록 owner: coordinator-agent.
- 결정: Consistent scalar moments를 같은 `3×3×3` volume quadrature로 계산하고 moment row-sum에서 nodal `6×6` block lumped mass를 유도한다. 기존 global 제약 뒤 analytic director null과 기존 stabilization의 decoupling을 이용해 finite 공간을 투영하고 sparse nodal whitening으로 FEAST에 연결한다.
- 근거: [Formulation 핵심 계약](formulation.md#핵심-계약), [mass M1~M10](formulation-mass.md), [eigen E1~E8](formulation-eigen.md).
- 영향: 곡면 coupling 및 mass/centroid·energy 차이를 명시하고 인공 drilling mass와 일반 dense Schur는 도입하지 않는다. Numerical Review는 수식·conditioning·FEAST controls·reference 준비를 독립 검토한다.
- 후속 검토: r1 NR-MFE-001로 확인된 기존 basis-dependent stabilization과 REQ-014 충돌은 MFE-ADR-007의 사용자 승인 개선 범위로 해결한다. r2 [V5](formulation-verification.md#v5-rigid-mode-coordinate-및-density-불변식)는 complete K와 supported partial BC 검증을 명시하며 수식의 독립 판정은 NR가 수행한다.

## MFE-ADR-007 — 기존 stabilization과 좌표 불변성 acceptance 정합

- 상태: 사용자 명시 승인; `MFE-OQ-003`의 좌표 공변적인 stabilization 개선 및 영향받는 정적/eigen 재검증 범위 추가안 선택.
- 발견 owner: numerical-review-agent; requirement intent owner: requirement-agent; 기록 owner: coordinator-agent.
- 근거: [NR-MFE-001](numerical-review.md#blocking-finding), [재현 가능한 반례](numerical-review-evidence.md#nr-mfe-001-직접-계산-반례).
- 발견: 동일 물리 partial rotation BC를 유지한 회전에서 기존 basis-dependent `kd=min(tangent diagonals)` 때문에 고유치가 상대 `1.1291343961675893e-5`만큼 달라진다. 새 mass 또는 analytic reduction의 확인된 결함은 아니다.
- 판단 근거: [Requirement owner 검토](requirements-evidence.md#nr-mfe-001-requirements-intent-검토)는 `FEM-REQ-MITC4-EIGEN-002/008/014`와 기존 shell의 fixed `kd` 계약을 대조했다. 알려진 지원 모델 반례를 제외하는 것은 acceptance 변경이며 기존 강성의 교체·삭제도 묵시적으로 승인되지 않았다.
- 검토했던 대안: 기존 stabilization과 partial BC 지원을 유지하며 좌표 의존성을 한계로 수용하고 `014` 적용 범위를 변경하는 안과, 좌표 공변적인 stabilization 개선 및 영향받는 기존 정적/eigen 계약·회귀 검증을 추가하는 안을 비교했다.
- 권고 owner와 이유: requirement-agent는 같은 물리 모델의 축 선택 의존성을 해결하는 후자를 권고한다. 기존 강성 계약 영향 검토와 정식화·회귀 검증 작업이 늘어나며 대체 수식은 Formulation 소유이다.
- 승인 근거: 2026-09-06 사용자 답변 “네 개선과 영향받는 기존 정적해석과 고유치해석의 재검증까지 범위에 포함해주세요.” Root가 원문과 권고안 B 승인 사실을 Coordinator에 전달했다.
- 결정 owner: user; 상세 요구 owner: requirement-agent; 개선 수식 owner: formulation-agent.
- 영향: 승인된 scope 변경으로 contract revision을 `r2`로 올린다. Requirement owner가 기존 물리 kernel 재사용과 개선된 stabilized pencil 보존을 구분하고 해당 static/eigen 회귀 요구를 명시한다. 영향받는 Research/Formulation/NR evidence는 owner별 최소 delta 검토 후 갱신한다.
- 경계: Partial BC 지원, 질량 흐름·FEAST 사용 mass·입력 N, reference 원본과 공통 tolerance를 유지한다. 기존 feature 보고서는 읽기 전용 이력으로 참조하며 현재 feature에서 대체되는 stabilization 계약의 범위를 명시한다. 사용자 승인으로 NR의 수치 gate나 구현 검증을 대신 통과시키지 않는다.
- 후속 근거: [Research R07](research-evidence.md#r07--r2-stabilization-근거와-영향)에 trace/spectral 기반의 기저 불변 scale 후보와 초기 고정 nonlinear 미분 구조, linear positive/null 조건을 기록했다. 이는 연구 후보이며 수식 채택은 Formulation owner가 수행한다.

## MFE-ADR-008 — 초기 physical trace 평균 stabilization scale

- 상태: r2 승인 개선 범위 안의 Formulation owner 수학 계약; 독립 NR에서 반례 해소 및 적용 경계 확인.
- 결정 owner: formulation-agent; 기록 owner: coordinator-agent.
- 결정: 초기 physical `K20`의 여덟 접평면 회전 대각 전체를 평균해 `k_ref=sum_i trace(R_i)/8`, `k_d=10^-3 k_ref`를 사용한다. Zero 대각도 포함하며 기존 numerical map과 nonlinear 초기 고정 lifecycle을 유지한다.
- 근거: [S1~S7](formulation-stabilization.md), [V8의 exact arithmetic·정적 evidence](formulation-verification.md#v8-r2-영향-확인과-bounded-evidence).
- 이유·경계: 접평면 기저의 scalar invariant를 쓰면서 spectral subtraction과 positive nodal block 선별을 피한다. 양성 inventory·단위·연산 순서·invalid 실패, partial BC에 남는 stabilization 및 기존 physical/nonphysical 구분은 해당 수학 계약을 따른다. 계수나 mass를 reference에 맞추어 조정하지 않는다.
- 검증 인계: NR-MFE-001의 새 algebraic target `k_d=19/4800`, `lambda=10369/450` 및 물리 tangent moment의 정적 response를 NR가 독립 직접 적분으로 확인했다. [r2 evidence](numerical-review-evidence.md)는 기존 실패와 새 complete K/질량/response/reaction 공변성 결과를 보존한다. 실제 C++/FEAST/reference 통과나 release evidence는 아니다.

## MFE-ADR-009 — NR 내부 controls와 외부 비교의 분리

- 상태: r2 Numerical Review owner가 고정한 수치·검증 계약; gate evidence audit 완료.
- 결정 owner: numerical-review-agent; 기록 owner: coordinator-agent.
- 결정: [Controls C1~C7](numerical-review-controls.md)의 같은 단위 metric/zero branch·analytic rank/conditioning·modal residual/Gram·FEAST parameter/seed/thread/storage/budget과 [27개 필수 case](numerical-review-cases.md)를 적용한다. 구체 수치의 원본은 해당 owner 문서다.
- 외부 비교: [reference-model](reference-model.md)의 source Step-2/mode-frame 1~10, Value=`omega²[T^-2]`, 10개 singleton family와 공통 TOLERANCE를 유지한다. 현재 양수 값의 실효 mode별 1%는 공통 RMS 정책의 결과이며 새 tolerance 변경이 아니다.
- 영향: I/O와 Planning/Implementation은 수치 threshold·mass·source identity를 임의로 바꾸지 않는다. 실제 FEAST known spectra·fresh reference 및 영향받은 static 회귀는 아직 수행할 필수 작업이다. 기존 static U/UR·reaction 역할을 새 eigen Value-only와 혼동하지 않는다.

## MFE-ADR-010 — Eigen 입력과 additive 결과 계약

- 상태: r2 I/O owner의 계약과 정적 evidence gate 확인.
- 결정 owner: io-definition-agent; 기록 owner: coordinator-agent.
- 결정: [입력 I1~I6](io-input.md)의 constant density·단일 frequency·입력 N·부수 옵션 subset을 적용한다. [O1~O5](io-schema.md)의 eigen procedure discriminant와 source step identity, 공개 N개 scalar/vector 및 전체 c 검증·FEAST call evidence를 저장한다.
- 이유·영향: 기존 static schema0/1의 의미와 mandatory inventory는 유지한다. 새 eigen은 `(schema_version=0, eigen_schema_version=1, analysis_procedure=linear-frequency)`와 Feature ID로 구분한다. Raw negative lambda와 unavailable real frequency를 명시적으로 분리하며 기존 non-Newton log lifecycle은 보존한다.
- 근거·경계: [M1~M5](io-mapping.md)의 책임·candidate replace 후 no-fail swap·원본 TXT full grammar 및 27개 요구 mapping을 따른다. 외부 projection은 공개 modes의 Value만 사용하고 10개 singleton family의 공통 판정을 유지한다. 영속 N개 vector는 내부 재현용이며 외부 mode-shape gate를 추가하지 않는다. 실제 parser/HDF5/FEAST/comparator 성공은 아직 미실행이다.

## MFE-ADR-011 — 유한 실행 준비와 검증 단위

- 상태: r2 Planning owner의 실행 계약 및 정적 gate 확인; 실제 실행은 미완료.
- 결정 owner: implementation-planning-agent; 사용자 실행 권한 해석: Root; 기록 owner: coordinator-agent.
- 결정: [계획](implementation-plan.md)의 별도 prep 1개 step 뒤 새 invocation으로 main 8개 step을 실행한다. 결합된 API/data 단위를 통합해 불필요한 full VERIFY 반복을 줄이고 각 step의 TDD·focused/full VERIFY·등록 Stop은 유지한다.
- 운영 근거: 기존 전체 검증의 약27.9분 합산 추정과 여러 1800초 deadline, nonlinear helper의 매번 solve 및 이미 로드된 Executor/Stop의 activation 경계를 [환경 E2/E3](implementation-environment.md)에 대조했다. 준비에서는 단일 유한 class timeout만 지정 후 실제 Executor main을 호출하며 runtime default의 최소 변경과 대응 Harness tests를 수행한다.
- 경계: Bootstrap은 기존 CLI option이나 sandbox 확대가 아니다. 정확한 값/명령은 Planning 문서의 원본을 따르고 Hook state·reentry·실행 메서드·retry·ownership guard를 override하지 않는다. Root/Coordinator도 active invocation 동안 non-owned 편집·커밋을 멈춘다. 보고 시점의 manual evidence와 Executor 종료 뒤 registered Stop/actual exit 사후 확인을 구분하며 성공 전 main activation을 하지 않는다.
- 실제 결과: [prep attempt1](coordination.md#execution-prep-attempt-1-실제-결과)은 기본 workspace-write에서 지정 `.codex/hooks.json` 변경을 거부당해 `blocked-environment`로 종료했다. Partial runtime/test/doc 변경과 마지막 test 수정 미검증을 보존한다. 현재 결정은 sandbox 확대나 성공 판정 권한을 포함하지 않으며, guarded Executor checkpoint 복구 계획 후 해당 실행 직전 명시적 사용자 승인 경계를 적용한다.

## MFE-ADR-012 — Source echo 분류 오탐의 bounded 운영 correction

- 상태: 실제 결함 재현 및 Planning의 최소 TDD·보존/activation 계획 확인; Correction 미실행.
- 발견·재현 owner: Root; 계획 owner: implementation-planning-agent; correction dispatch owner: coordinator-agent.
- 근거: [실제 raw/순수함수 재현](../../.harness/build/mitc4-eigen-evidence/prep/attempt1/classifier-observation.json), [복구 R4](implementation-recovery.md#r4-조건부-exact-dfa-invocation과-후속-검증), [prep TDD](../../phases/mitc4-shell-feast-eigen-execution-prep/step0.md).
- 결정: 성공한 source-read 출력의 helper marker를 실제 runtime failure로 오인하는 분류 결함만 기존 `scripts/execute.py`/`tests/test_execute.py` 안에서 먼저 수정한다. 진짜 helper 진단, 명시 terminal/history, 실제 wrapper timeout만 허용되는 retry 및 sandbox/ownership 보호를 유지한다.
- 순서·이유: 기존 timeout-only AST guard로 현재 blocked/WIP를 먼저 보존하고 별도 Correction 뒤 새 Executor process를 시작한다. 이미 import된 classifier는 child source 수정만으로 바뀌지 않으며 reload/guard override로 성공을 만들지 않는다. 실제 Hook 쓰기 거부는 별도 환경 blocker로 보존한다.
- 경계: Physics/schema/tolerance `r2`와 선행6개 기술 계약을 바꾸지 않는다. Correction은 별도 signature의 unused allowance 확인 후 명시 dispatch하며 성공·검증·커밋은 실제 결과 뒤에만 기록한다. Exact-run sandbox 사용자 승인과 full VERIFY는 유지한다.