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

# MITC4 Shell Mass·FEAST Eigen 2 결정 기록

- Feature ID: `mitc4-shell-feast-eigen2`
- Owner: 메인 assistant
- Requirement baseline revision: `r1`

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
[공통 ADR](../ADR.md#adr-028). 사용자 요청·현재 checklist는 [PRD](PRD.md),
지역 지침·소유권은 [FEATURED_AGENTS](FEATURED_AGENTS.md)를 따른다.

## MFE2-ADR-001 — 새로운 requirement baseline과 작업 범위

- 상태: 사용자 명시 요청, 2026-09-08.
- 결정: `mitc4-shell-feast-eigen2`를 새 Feature ID로 사용하고 requirement 단계만 수행한다. 변경 문서는 이 폴더에 작성하며 완성된 변경을 경로별로 커밋한다.
- 근거: “mitc4-shell-feast-eigen2 라는 이름으로 처음 requirement 작업부터 시작”, “requirement 단계만 진행”, “변경사항들을 깃에 커밋”.
- 영향: 새 요구 ID·r1을 작성한다. 기존 Feature·phase의 미커밋 변경과 실패 이력은 보존하고 research 이후 작업·push는 이번 범위에 포함하지 않는다.
- 이유: 요구사항을 현재 운영 기준에서 다시 검토하면서 기존 작업과 결과를 혼동하지 않기 위함이다.

## MFE2-ADR-002 — 기존 명시 사용자 요구의 적용

- 상태: 기존 명시 사용자 결정의 재시작 기준으로서 기록. 새로운 수학·schema 승인 아님.
- 결정: consistent→lumped→FEAST, 입력의 mode count, 고유치 Value-only 외부 비교, 좌표 공변적 stabilization 개선 및 영향받는 static/eigen 재검증, reference/temp 제외의 의미를 새 요구사항에 반영한다.
- 근거: 기존 [ADR](../mitc4-shell-feast-eigen/ADR.md)의 MFE-ADR-001·002·004·005·007·013 및 [requirements](../mitc4-shell-feast-eigen/requirements.md) r3. 기존 ADR에는 질량 사용·개선 범위·제외에 관한 사용자 답변이 명시되어 있다.
- 영향: 알려진 사용자 결정을 다시 양자택일 질문으로 만들지 않는다. 기존 formulation/NR/I/O의 상세 수식·control·영속 식별자를 자동 채택하거나 통과로 표시하지 않는다.
- 한계: 일부 기존 r3 문서는 현재 worktree의 미커밋 자료다. 필요한 요구의 실제 의미와 제외 목록은 새 requirements에 독립적으로 명시하고 이전 HEAD에 동일 내용이 있다고 주장하지 않는다.

## MFE2-ADR-003 — 참고 자료와 새 evidence의 경계

- 상태: 현행 프로젝트 기준을 적용한 문서 작성 결정.
- 결정: 기존 요구사항·근거는 요구 정의의 입력, research/formulation/NR/I/O 문서는 후속 검토 후보로 구분한다. 기존 implementation/environment/recovery/coordination/phase는 역사적 진단 자료다.
- 이유: 유용한 연구·반례를 재사용하되 과거 gate와 환경 통과를 새 Feature의 검증으로 오인하지 않게 한다.
- 영향: 새 정식화의 채택·수치 기준·source/result mapping은 후속 전문 작업이 필요할 때 정의한다. 이 요구사항 단계는 solver 구현·FEAST 실행·reference 비교·환경 준비 통과를 선언하지 않는다.
- 보존: reference artifact와 `docs/TOLERANCE.md`는 읽기 전용이다. 제외 예제의 재사용이나 comparison tolerance 완화로 알려진 문제를 숨기지 않는다.

## MFE2-ADR-004 — 현행 운영 방식과 요구사항 완료

- 상태: [ADR-028](../ADR.md#adr-028) 적용.
- 결정: 메인이 관리 문서·검토·커밋을 맡고 Requirement specialist는 할당된 요구사항 문서만 작성한다. 상태는 PRD checklist에만 둔다.
- 영향: 고정 9단계 dispatch, 별도 planning/correction/release profile, 자동 Git·hook, phase payload·retry budget을 새 요구사항으로 복원하지 않는다.
- 검증: 문서·ID·출처·링크·scope의 정적 확인을 수행한다. 실제 동작 검증 의무와 기존 명시 감사 요구의 보존은 문서 작성과 별개이며 이번에는 실행하지 않는다.

## MFE2-ADR-005 — Research부터 I/O 계약까지의 후속 작업

- 상태: 사용자 명시 요청, 2026-09-08. Owner: 메인 assistant.
- 결정: requirement r1을 기준으로 research, formulation, 독립 numerical review, io-definition을 진행하고 변경을 커밋한다. ADR-001의 requirement-only 작업 범위는 이 후속 요청으로 확장된다.
- 승인 근거: “research 단계부터 io-definition 단계까지 작업을 진행”, “작업시간이 30분 이상 걸리면 작업을 중지하고 진행사항과 오래걸리는 이유를 보고”.
- 영향: 기존 수식·control·schema는 새 전문 검토를 거쳐 채택 여부를 명시한다. 문서 승인과 실제 solver 검증을 구분하며 구현·reference 실행·push는 수행하지 않는다.
- 제한: 2026-09-08 12:07:56 UTC부터 12:37:56 UTC까지. 제한 내 미완료 작업은 통과로 바꾸지 않고 상태·원인을 보고한다.

## MFE2-ADR-006 — 정식화 r1의 선택과 연구 gap 처리

- 상태: 승인된 요구 범위 안의 formulation 선택. 독립 numerical 판정은 별도 기록한다. Owner: formulation-agent; 기록: 메인 assistant.
- 결정: [정식화](formulation.md)의 27점 consistent moments→nodal block lumping, 실제 BC 우선 analytic null 제거·nodal whitening 및 초기 physical rotary trace 평균 stabilization을 이번 수학 계약으로 선택한다. Nonlinear objective potential과 초기 scale 고정 lifecycle을 유지한다.
- 이유: 질량 유도 관계·drilling null·부분 회전 제약을 보존하고 기존 최소 대각 scale의 기저 의존성을 해결한다. 기존 유도의 채택 범위를 새 문서에 명시하며 과거 pass를 승계하지 않는다.
- FEAST: 독립 outer enclosure와 성공 total count를 기준으로 lower endpoint를 고정하고 upper-prefix 축소만 선택적으로 사용한다. 미확인 empty-count 성공에 의존하지 않으며 최적화 실패 시 마지막 확인된 구간을 사용한다.
- 근거·한계: [연구 G01/G02](research-evidence.md)에서 count-only 빈 구간 및 작은 workspace 보장이 확인되지 않았다. 보수적 workspace와 실제 runtime·memory 검증 의무를 남기며 backend 통과를 선언하지 않는다.
- 승인 경계: 기존 사용자 요구의 수학적 구체화이며 새로운 물리 범위·외부 tolerance·공개 호환성 변경은 없다. 수치 controls·검토는 NR, 영속 schema는 I/O가 소유한다.

## MFE2-ADR-007 — 독립 수치 검토와 comparison family

- 상태: numerical-review-agent의 독립 `pass-for-io-definition`, 2026-09-08. Owner: numerical-review-agent; 기록: 메인 assistant.
- 근거: [검토](numerical-review.md), [새 계산](numerical-review-evidence.md). Geometry부터 complete K·질량·부분 제약 정적 응답을 재계산하여 `lambda=10369/450` 및 좌표 공변성을 확인했다. 별도 rational mass oracle도 새로 실행했다.
- 결정: [내부 controls](numerical-review-controls.md)와 [27개 사례](numerical-review-cases.md)를 적용한다. 초기 enclosing count 재시도는 최초 포함 3회, 이후 lower endpoint 고정·upper search·전체 count/solve 유한 한계를 명시했다. B=0의 시작 구간은 (-1,1)로 고정했다.
- 외부 비교: 원본 TXT의 literal modal frame과 유일한 source Step-2를 [reference-model](reference-model.md)에 대응한다. 같은 frame 규칙에 따라 10개 singleton Value blocking family를 정의하고 공통 행 5%·RMS 1% 정책을 그대로 적용한다. 이번 양수 singleton의 실효 각 Value 한계는 RMS 1%다.
- 영향·한계: 확인된 수학 차단 이슈 없이 I/O 정의를 진행할 수 있다. 이 판정은 구현·실제 FEAST·정적 회귀·외부 비교·Physics·release 통과가 아니다. Runtime count/cluster/ABI/workspace와 메모리 검증은 후속 필수 evidence다.

## MFE2-ADR-008 — Eigen I/O의 additive 계약과 이번 작업 종료

- 상태: 요청 범위의 I/O 정의 완료 및 메인 계약 대조 완료, 2026-09-08. Owner: io-definition-agent; 기록: 메인 assistant.
- 결정: [I/O](io.md)의 source density/Frequency/동차 BC·정확한 no-op allowlist를 사용한다. 기존 static schema0/1을 보존하고 eigen discriminator `(schema_version=0, feature_id=mitc4-shell-feast-eigen2, analysis_procedure=linear-frequency, eigen_schema_version=1)`를 추가한다.
- Identity: storage Step-1과 source Step-2를 구분한다. 공개 N개 scalar/global normalized vectors와 전체 c개 validation evidence를 분리한다. 원본 TXT Value만 source modal frame에 직접 대응하며 외부 mode-shape gate를 추가하지 않는다.
- 이유: 실제 parser·model·writer의 현재 경계를 보존하면서 새 procedure의 input/result 의미를 명확히 하기 위함이다. Candidate self-check·final 교체와 별도 live log lifecycle을 유지한다.
- 승인 경계: 이미 승인된 새 eigen procedure의 상세 schema 정의이며 기존 static 호환성·물리·외부 tolerance 변경은 없다. 일반 routine 정의에 반복 사용자 승인 gate를 추가하지 않는다.
- 종료: 요청한 네 문서 작업을 시간 제한 안에 마친다. 링크·ID·coverage·소스 대조·diff 정적 확인과 독립 수학 oracle를 evidence로 남기고, 구현·실제 solver/reference/physics 실행은 미실행으로 기록한다. 새 Feature 변경만 커밋하고 기존 사용자 변경은 보존한다.

## MFE2-ADR-009 — Implementation 실행과 시간 제한 해제

- 상태: 사용자 명시 요청, 2026-09-09 KST. Owner: 메인 assistant.
- 근거: “implementation 단계를 진행해주세요”, “implementation 단계에서 30분 제한은 없습니다”.
- 결정: 확정된 r1 계약을 구현하고 동작별 테스트·실제 FEAST·남는 필수 회귀/reference와 독립 검토를 진행한다. 30분 시간 제한을 적용하지 않는다.
- 영향: [구현 계획](implementation-plan.md)의 파일 소유권으로 병행 작업하고 메인이 CMake 등록·빌드·통합·커밋을 조정한다. 수치/공개 schema/지원 범위를 구현 결과에 맞춰 변경하지 않는다. 공통 문서·기존 사용자 변경·reference를 보존한다.

## MFE2-ADR-010 — 실제 실행에서 드러난 계약 충돌

- 상태: 문제 기록·후속 제안, **수치 계약 변경 미승인**. Owner: 메인 assistant.
- 근거: [실행 결과](implementation-verification.md), [독립 수치 검토](implementation-numerical-review.md), [S3 검토](implementation-numerical-review-s3-static.md).
- 관찰: 원본 모델은 고정 FEAST trace stopping의 실제 반환값에서 전체 c residual 기준을 넘는다. S3 public static은 rotation-only drilling의 미평형 모멘트 때문에 실패한다.
- 현재 처리: r1 controls·tolerance·물리 식을 유지하고 실패를 명시한다. 요청 N 밖의 모드를 버리거나 reaction에서 torque를 제거하지 않는다. 구현 진행분은 커밋하되 기능 완료로 표시하지 않는다.
- 당시 후속 제안: residual stopping 후보의 FEAST 제어와 S3 정식화/회복/평형 계약을 사용자 결정 후 formulation·NR에서 재검토한다. 이 기록 시점에는 채택·승인된 변경이 없었다. 이후 FEAST 제어만 ADR-011로 변경한다.

## MFE2-ADR-011 — FEAST residual stopping과 S3 후속 분리

- 상태: 사용자 명시 승인, 2026-09-10. Owner: 메인 assistant; 수치 검토: numerical-review-agent.
- 승인 근거: “FEAST 잔차 초과 문제를 Trace 기반 종료 → residual 기반 종료로 변경”, “S3 문제는 추후에 고려”.
- 결정: C-index `fpm[5]`를 `1`에서 `0`으로 변경한다. `fpm[2]=12`, `fpm[3]=20`, count/solve 구간·capacity·seed·thread·실패 정책 및 전체 c개 독립 `1e-10` 검증은 유지한다.
- 이유: trace 변화의 수렴만으로는 원본 모델 전체 고유쌍의 독립 잔차를 충족하지 못했다. 개별 잔차를 사용하는 backend 종료를 선택하되 backend 성공을 독립 검증으로 대체하지 않는다.
- 영향: [정식화 E5](formulation-eigen.md), [수치 controls C5](numerical-review-controls.md), backend와 HDF5 writer의 control 검증을 함께 갱신한다. 기존 schema의 실제 `base_fpm[5]` 기록값이 바뀌며 field·shape·단위와 reference mapping은 유지한다.
- 검증: [실행 결과](implementation-verification.md) 및 [독립 수치 검토](implementation-feast-residual-review.md)에 새 실행을 기록한다. 기존 trace 실패 evidence는 당시 결과로 보존한다.
- 범위: S3 정식화·부분 회전 BC·reaction·평형 기준은 변경하지 않고 알려진 충돌을 후속 과제로 유지한다. S3를 해결하거나 unsupported로 재분류한 결정이 아니다. 외부 reference와 공통 tolerance도 유지한다.

## MFE2-ADR-012 — 첫 구현의 외부 고유치 5% 수용

- 상태: 사용자 명시 승인, 2026-09-10. Owner: 메인 assistant.
- 승인 근거: “5% 이내면 첫 구현이므로 Abaqus와의 고유치 정확도 향상은 추후에 진행”, “구현을 마무리”.
- 결정: [공통 ADR-029](../ADR.md#adr-029)와 [TOLERANCE 예외](../TOLERANCE.md#승인된-mitc4-eigen-첫-구현-예외)의 `mitc4-eigen-first-implementation` 정책을 적용한다. Mode별 Value relative/RMS limit은 inclusive5%다.
- 영향: Requirement022, reference model, I/O mapping과 comparator/report를 갱신한다. 같은 모드 identity·singleton family·원본 artifact와 내부 all-c1e-10 기준을 유지한다. 다른 기능의 공통 RMS1%는 변경하지 않는다.
- 범위: 첫 구현의 외부 고유치 정확도 향상 및 ADR-011의 S3는 후속 과제로 유지한다. 나머지 필수 구현/실패 보존 검사는 실제 evidence로 마무리하며 미실행을 통과로 표시하지 않는다.
- 결과: [구현 결과](implementation-verification.md)와 [첫 구현 독립 검토](implementation-first-version-review.md)에 새 정책의 fresh 검증 및 제한을 기록한다. 과거1% 비교 실패는 당시 계약의 이력으로 보존한다.
- 통합 승인: 사용자는 구현·검증 완료 후 `dev` 병합과 push를 명시 요청했다. 메인은 통과한 변경을 커밋하고 `dev`에 반영하며 관련 없는 사용자 worktree 변경은 보존한다. 외부 release/tag 승인으로 확대하지 않는다.