docs: record eigen2 implementation scope and verification plan

2026-09-09 02:14:29 +09:00
parent ad89661e71
commit e74ac247db
4 changed files with 74 additions and 9 deletions
@@ -72,3 +72,10 @@
 - 이유: 실제 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를 보존한다.
@@ -3,7 +3,7 @@
 - Feature ID: `mitc4-shell-feast-eigen2`
 - Owner: 메인 assistant
 - Requirement baseline revision: `r1`
- 현재 작업: requirement r1을 기준으로 research → formulation → numerical-review → io-definition 문서 작업을 완료했다. 구현·solver 실행 검증은 후속 의무다.
+- 현재 작업: 확정된 requirement/formulation/NR/I/O r1을 기준으로 implementation과 필요한 실행 검증을 진행한다.
 - 목적: MITC4 질량행렬과 FEAST 고유진동 해석의 요구사항을 이론·수학·수치 검토·입출력 계약으로 구체화한다.
 - 현재 checklist: [PRD](PRD.md#현재-checklist).

@@ -19,9 +19,9 @@
 - 새 요구사항은 `FEM-REQ-MITC4-EIGEN2-###` ID를 사용한다. 기존 ID는 추적용 대응 관계에만 남긴다.
 - Requirement는 관찰 가능한 동작·범위·검증 의도를 소유한다. 특정 lumping/축소 수식, FEAST parameter, HDF5 layout, 수치 threshold는 새로 결정하지 않는다.
 - `reference/temp` 예제는 원본·옛 경로·복사본·cache를 통해서도 검증에 사용하지 않는다. 제외 목록은 requirements의 원본 정의를 따른다.
- 변경은 할당된 이 폴더의 문서로 제한한다. 기존 Feature·phase·source·test·config·reference는 수정하지 않는다.
- 이번 문서 작업의 완료는 solver 기능 완료가 아니다. 구현 등 요청 범위 밖의 작업을 진행하거나 빈 후속 보고서를 만들지 않는다.
- 사용자 시간 제한은 [PRD](PRD.md)의 시작 시각부터 30분이다. 도달하면 중지하고 실제 진행 상태와 오래 걸린 이유를 보고한다.
+- 구현 변경은 [implementation-plan](implementation-plan.md)의 할당 source·test·build 등록과 이 Feature 문서에 제한한다. 기존 Feature·phase의 사용자 변경과 reference는 보존한다.
+- 문서·단일 kernel/backend의 완료를 solver 기능 완료로 보고하지 않는다. 필요한 실제 실행·독립 검토 evidence를 확인한다.
+- 사용자는 implementation 단계의 30분 제한을 명시 해제했다. 이전 문서 단계의 시간 제한은 이력이다.

 ## 문서 목록과 소유권

@@ -36,5 +36,6 @@
 | [formulation.md](formulation.md), [질량·stabilization](formulation-mass-stabilization.md), [eigen](formulation-eigen.md) | formulation-agent | 구현 가능한 수학 계약·기존 유도 채택 경계 |
 | [numerical-review.md](numerical-review.md), [evidence](numerical-review-evidence.md), [controls](numerical-review-controls.md), [cases](numerical-review-cases.md), [reference-model](reference-model.md) | numerical-review-agent | 독립 수학 검토·실제 검산·수치 기준·검증 사례·외부 비교 의미 |
 | [io.md](io.md), [input](io-input.md), [schema](io-schema.md), [mapping](io-mapping.md) | io-definition-agent | 입력·진단·내부 소유권·영속 결과·비교 projection 계약 |
+| [implementation-plan.md](implementation-plan.md) | 메인 assistant | 구현 할당·검증 순서와 실행 경계 |

 반환은 결과·변경 파일·정적 확인·미해결 항목으로 충분하다. Git 경로 선택·커밋과 최종 결과 확인은 메인이 수행한다.
@@ -3,7 +3,7 @@
 - Feature ID: `mitc4-shell-feast-eigen2`
 - Owner: 메인 assistant
 - Requirement baseline revision: `r1`
- 상태: requirement r1에 이어 research·formulation·독립 numerical review·io-definition 문서 작업 완료. Solver 구현·실행 검증은 미실행이다.
+- 상태: requirement/formulation/NR/I/O r1 문서 완료. 후속 사용자 요청에 따라 implementation·실행 검증 진행 중이다.

 기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
 [공통 ADR](../ADR.md#adr-028). 지역 지침은 [FEATURED_AGENTS](FEATURED_AGENTS.md),
@@ -24,6 +24,11 @@ solver build/test·reference 비교와 release 감사는 포함하지 않는다.
 작업시간 제한은 30분이다. 시작은 2026-09-08 12:07:56 UTC이며 12:37:56 UTC에 도달하면
 진행 중인 작업을 중지하고 실제 완료·미완료 항목과 지연 이유를 보고한다.

+2026-09-09 KST 사용자는 **implementation 단계를 진행**하도록 요청하고 **implementation
+단계의 30분 제한은 없다**고 명시했다. 현재 범위는 [구현 계획](implementation-plan.md)에 따른
+코드·테스트·실제 FEAST 및 필수 reference/회귀 검증과 작업별 커밋이다. 앞의 30분 제한은
+완료된 문서 작업의 이력이다. 원본 reference 생성·변경과 push/release는 포함하지 않는다.
+
 ## 솔버 기능의 요구 범위 요약

 기존 사용자 결정에 기록된 다음 의미를 새 요구사항의 출발점으로 사용한다.
@@ -70,7 +75,15 @@ solver build/test·reference 비교와 release 감사는 포함하지 않는다.

 이 checklist는 문서 작업 상태다. Solver 구현·실제 FEAST 실행·회귀 및 외부 reference 비교의 통과를 뜻하지 않는다.

-## 이번 결과와 남은 실행 의무
+- [ ] 질량·stabilization과 독립 analytical/invariant 테스트 구현·검증.
+- [ ] 실제 FEAST backend·count/cluster/zero/실패 controls와 runtime 검증.
+- [ ] Density/Frequency semantic·source identity·진단 및 입력 테스트.
+- [ ] Constraint-first 축소·modal recovery·별도 eigen state/procedure 구현.
+- [ ] HDF5 additive schema·candidate 보존·Value comparator 및 통합 테스트.
+- [ ] 제외 예제 사용 없이 남는 static/내부 회귀·전체 build/test·필수 reference 실행.
+- [ ] 관련 독립 numerical/physics 확인, 결과·한계 기록과 커밋.
+
+## 이전 문서 단계의 결과와 구현 입력

 Research부터 I/O까지 요청한 문서 작업과 독립 수학 검산을 30분 제한 안에 완료했다.
 19개 Feature 문서의 링크·UTF-8·diff와 27개 요구/검증 case identity·coverage를 확인했다.
@@ -78,6 +91,7 @@ Research부터 I/O까지 요청한 문서 작업과 독립 수학 검산을 30

 다음 작업의 입력은 [정식화](formulation.md), [독립 검토](numerical-review.md),
 [controls](numerical-review-controls.md), [cases](numerical-review-cases.md), [I/O](io.md)다.
-Density/Frequency semantic·mass/FEAST·eigen state/writer 구현, 실제 backend의 count/cluster/
-workspace/ABI 확인, MSVC build/test와 남는 static·eigen reference 및 물리 검증은 미실행이다.
-Pressure 제외 예제의 fresh 외부 coverage 부재도 유지한다. 이 후속 실행은 이번 작업에 포함하지 않는다.
+문서 단계 종료 당시 Density/Frequency semantic·mass/FEAST·eigen state/writer 구현, 실제
+backend와 MSVC build/test·reference·물리 검증은 미실행이었다. 현재 사용자가 승인한 구현은
+[implementation-plan](implementation-plan.md)에 따라 이 후속 실행을 포함하며, 진행 상태는
+위 checklist를 따른다. Pressure 제외 예제의 fresh 외부 coverage 부재는 유지한다.
@@ -0,0 +1,43 @@
+# MITC4 eigen 구현 계획
+
+- Feature: `mitc4-shell-feast-eigen2`; Owner: 메인 assistant.
+- 기준: [프로젝트 지침](../../AGENTS.md), [PRD](../PRD.md), [ADR](../ADR.md),
+  [정식화](formulation.md), [NR controls](numerical-review-controls.md),
+  [검증 사례](numerical-review-cases.md), [I/O](io.md).
+- 실행 권한·현재 checklist는 [Feature PRD](PRD.md), 시간 제한 해제는 [Feature ADR](ADR.md)의 ADR-009를 따른다.
+
+## 변경 묶음과 소유권
+
+| 묶음 | Owner / 실제 경로 | 구현과 검증 |
+| --- | --- | --- |
+| 질량·stabilization | implementation-agent `eigen2_mass_impl`; `include/fesa/elements/mitc4_shell.h`, `src/fesa/elements/mitc4_shell.cpp`, 해당 element unit tests | 27점 consistent moments→derived lumped, trace mean. 독립 flat/warped mass, drill null·좌표/부분 BC와 기존 물리 kernel 검사 |
+| FEAST backend | implementation-agent `eigen2_feast_impl`; 새 `include/fesa/solvers/eigen/`, `src/fesa/solvers/eigen/`와 unit tests | 실제 MKL 호출, fixed-lower count/search, controls·checked storage·all-c 검증·실패 evidence. 실제 known spectra/zero/repeated/endpoint 및 thread 복원 |
+| 입력·Domain | implementation-agent `eigen2_input_impl`; `model_types.h`, `domain.h/.cpp`, `domain_mapping_context.cpp`, eigen mapper/model tests | Material별 density, 독립 Frequency payload와 common boundary view, source Step-2/N 보존, exact allowlist와 fail-closed 진단 |
+| 축소·procedure·state | 메인; 새 `analysis/eigen_*`, 관련 `AnalysisModel`/`DofManager`/prepared/application 연결 | 실제 BC→analytic null→nodal SPD whitening, sparse congruence, original-free 복구·정규화/Gram/에너지, 후보 state. 작은 직접 pencil 및 partial-BC 통합 검증 |
+| 결과·비교·회귀 | 메인 또는 후속 명시 할당 owner; 새 eigen HDF5 writer/self-check, eigen reference comparator, 해당 tests와 기존 제외 inventory 변경 | Static schema 유지, source identity·N/c 구분, candidate 보존, TXT Value-only 공통 tolerance, retained static와 synthetic coverage |
+| 빌드·Git·Feature 기록 | 메인; `src/fesa/CMakeLists.txt`, `tests/CMakeLists.txt`, 이 Feature의 관리/결과 문서 | 동시 빌드 충돌 방지, 명시 경로별 stage/commit, 사용자 변경 보존 |
+
+서로 다른 owner의 파일을 덮어쓰지 않는다. Shared API는 구현 전에 메인에 전달하고 불일치는
+계약 원본과 대조하여 수정한다. Vendor type은 private adapter에만 둔다. 이미 승인된 수식을
+다시 선택하거나 시간 절약을 위해 dense global Schur·인공 mass·lower mode 누락을 허용하지 않는다.
+
+## 검증 순서
+
+1. 현재 설정의 configure/build와 검사 inventory를 확인한다. 가능한 결함 재현 후 최소 수정하고
+   [27개 사례](numerical-review-cases.md)와 [IO-T01–11](io.md)에 각 테스트를 연결한다.
+2. 묶음별 unit/integration 검사를 실행한다. Actual FEAST probe는 mock으로 대체하지 않는다.
+   수학/자료 조립을 변경하면 필요한 독립 numerical 검토를 받는다.
+3. CLI→원본 입력→HDF5→TXT Value comparison을 fresh 실행한다. 원본 TXT/CSV를 수정하거나
+   제외 예제의 옛 경로·복사본·cache로 성공 evidence를 만들지 않는다.
+4. 영향받는 shell/shellNL/linear-limit, nonlinear tangent/objectivity/평형·state,
+   pressure synthetic·기타 기존 회귀를 보존한다. 제외된 복합 테스트의 retained 관찰은 분리한다.
+5. 기능 완료 시 구성된 전체 build/test와 필수 reference를 한 번 실행하고 독립 물리 검토와
+   실제 결과·실패·미실행을 기록한다. 실패 수치를 expected로 복사하거나 tolerance를 완화하지 않는다.
+
+현재 `.harness/config.json`은 `mfe-workspace-msvc-ninja-debug` configure/build/test preset과
+`.harness/build-ninja-msvc-debug`를 선택한다. 개인 preset의 dependency 경로는 commit하지 않는다.
+Focused 실행은 해당 CMake target/CTest filter, 전체 검증은 `python scripts/execute.py`다.
+메인이 빌드 실행을 직렬화한다. C++에는 MSVC x64 Debug `/W4 /WX` 기준을 적용한다.
+
+FEAST runtime/count/workspace·원본 eigen 비교의 성공 여부는 아직 미확인이다. 실패 시 원인과
+적용 계약을 추적하고, 실제 필수 계약 충돌이 있을 때만 사용자 결정 경계로 반환한다.