docs: plan MITC4 mass and FEAST implementation

2026-09-06 05:37:30 +09:00
parent 1d4f5ac44a
commit d533b61541
20 changed files with 2280 additions and 6 deletions
@@ -0,0 +1,167 @@
+# Step 7: Value-only comparator·fresh reference·구현 evidence
+
+- Feature ID: `mitc4-shell-feast-eigen`
+- Plan owner: `implementation-planning-agent`
+- Execution owner: `implementation-agent`
+- Input contract revision: `r2`
+- Phase: `mitc4-shell-feast-eigen`
+- Dependency: 동일 phase의 Step 6 completed
+- Requirement IDs: `FEM-REQ-MITC4-EIGEN-001`, `FEM-REQ-MITC4-EIGEN-002`, `FEM-REQ-MITC4-EIGEN-003`, `FEM-REQ-MITC4-EIGEN-004`, `FEM-REQ-MITC4-EIGEN-005`, `FEM-REQ-MITC4-EIGEN-006`, `FEM-REQ-MITC4-EIGEN-007`, `FEM-REQ-MITC4-EIGEN-008`, `FEM-REQ-MITC4-EIGEN-009`, `FEM-REQ-MITC4-EIGEN-010`, `FEM-REQ-MITC4-EIGEN-011`, `FEM-REQ-MITC4-EIGEN-012`, `FEM-REQ-MITC4-EIGEN-013`, `FEM-REQ-MITC4-EIGEN-014`, `FEM-REQ-MITC4-EIGEN-015`, `FEM-REQ-MITC4-EIGEN-016`, `FEM-REQ-MITC4-EIGEN-017`, `FEM-REQ-MITC4-EIGEN-018`, `FEM-REQ-MITC4-EIGEN-019`, `FEM-REQ-MITC4-EIGEN-020`, `FEM-REQ-MITC4-EIGEN-021`, `FEM-REQ-MITC4-EIGEN-022`, `FEM-REQ-MITC4-EIGEN-023`, `FEM-REQ-MITC4-EIGEN-024`, `FEM-REQ-MITC4-EIGEN-025`, `FEM-REQ-MITC4-EIGEN-026`, `FEM-REQ-MITC4-EIGEN-027`
+- Logical cases: `MFE-C06`, `MFE-C08`, `MFE-C09`, `MFE-C11`, `MFE-C12`, `MFE-C17`, `MFE-C18`, `MFE-C20`, `MFE-C23`, `MFE-C24`, `MFE-C25`, `MFE-C26`, `MFE-C27`
+- I/O obligations: `IO-T01`, `IO-T04`, `IO-T05`, `IO-T07`, `IO-T08`, `IO-T09`, `IO-T10`, `IO-T11`
+
+## 필수 입력과 계약
+
+Feature 폴더는 `docs/mitc4-shell-feast-eigen/`다. 아래 current r2 입력을 읽고 기존 완료 Step 코드와 evidence를 대조한다. 연결된 upstream contract는 read-only다.
+
+- [AGENTS.md](../../AGENTS.md)
+- [docs/SOLVER_AGENT_DESIGN.md](../../docs/SOLVER_AGENT_DESIGN.md)
+- [docs/FEATURE_DOCUMENTATION.md](../../docs/FEATURE_DOCUMENTATION.md)
+- [docs/PRD.md](../../docs/PRD.md)
+- [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+- [docs/ADR.md](../../docs/ADR.md)
+- [docs/CODINGSTYLE.md](../../docs/CODINGSTYLE.md)
+- [docs/TOLERANCE.md](../../docs/TOLERANCE.md)
+- [.codex/skills/fem-implementation-tdd/SKILL.md](../../.codex/skills/fem-implementation-tdd/SKILL.md)
+- [.agents/skills/harness/SKILL.md](../../.agents/skills/harness/SKILL.md)
+- [.codex/agents/implementation-agent.toml](../../.codex/agents/implementation-agent.toml)
+- [docs/mitc4-shell-feast-eigen/FEATURED_AGENTS.md](../../docs/mitc4-shell-feast-eigen/FEATURED_AGENTS.md)
+- [docs/mitc4-shell-feast-eigen/PRD.md](../../docs/mitc4-shell-feast-eigen/PRD.md)
+- [docs/mitc4-shell-feast-eigen/ADR.md](../../docs/mitc4-shell-feast-eigen/ADR.md)
+- [docs/mitc4-shell-feast-eigen/coordination.md](../../docs/mitc4-shell-feast-eigen/coordination.md)
+- [docs/mitc4-shell-feast-eigen/requirements.md](../../docs/mitc4-shell-feast-eigen/requirements.md)
+- [docs/mitc4-shell-feast-eigen/requirements-evidence.md](../../docs/mitc4-shell-feast-eigen/requirements-evidence.md)
+- [docs/mitc4-shell-feast-eigen/research.md](../../docs/mitc4-shell-feast-eigen/research.md)
+- [docs/mitc4-shell-feast-eigen/research-evidence.md](../../docs/mitc4-shell-feast-eigen/research-evidence.md)
+- [docs/mitc4-shell-feast-eigen/formulation.md](../../docs/mitc4-shell-feast-eigen/formulation.md)
+- [docs/mitc4-shell-feast-eigen/formulation-mass.md](../../docs/mitc4-shell-feast-eigen/formulation-mass.md)
+- [docs/mitc4-shell-feast-eigen/formulation-eigen.md](../../docs/mitc4-shell-feast-eigen/formulation-eigen.md)
+- [docs/mitc4-shell-feast-eigen/formulation-verification.md](../../docs/mitc4-shell-feast-eigen/formulation-verification.md)
+- [docs/mitc4-shell-feast-eigen/formulation-stabilization.md](../../docs/mitc4-shell-feast-eigen/formulation-stabilization.md)
+- [docs/mitc4-shell-feast-eigen/numerical-review.md](../../docs/mitc4-shell-feast-eigen/numerical-review.md)
+- [docs/mitc4-shell-feast-eigen/numerical-review-evidence.md](../../docs/mitc4-shell-feast-eigen/numerical-review-evidence.md)
+- [docs/mitc4-shell-feast-eigen/numerical-review-controls.md](../../docs/mitc4-shell-feast-eigen/numerical-review-controls.md)
+- [docs/mitc4-shell-feast-eigen/numerical-review-cases.md](../../docs/mitc4-shell-feast-eigen/numerical-review-cases.md)
+- [docs/mitc4-shell-feast-eigen/reference-model.md](../../docs/mitc4-shell-feast-eigen/reference-model.md)
+- [docs/mitc4-shell-feast-eigen/io.md](../../docs/mitc4-shell-feast-eigen/io.md)
+- [docs/mitc4-shell-feast-eigen/io-input.md](../../docs/mitc4-shell-feast-eigen/io-input.md)
+- [docs/mitc4-shell-feast-eigen/io-schema.md](../../docs/mitc4-shell-feast-eigen/io-schema.md)
+- [docs/mitc4-shell-feast-eigen/io-mapping.md](../../docs/mitc4-shell-feast-eigen/io-mapping.md)
+- [docs/mitc4-shell-feast-eigen/implementation-plan.md](../../docs/mitc4-shell-feast-eigen/implementation-plan.md)
+- [docs/mitc4-shell-feast-eigen/implementation-environment.md](../../docs/mitc4-shell-feast-eigen/implementation-environment.md)
+- [docs/mitc4-shell-feast-eigen/implementation-interfaces.md](../../docs/mitc4-shell-feast-eigen/implementation-interfaces.md)
+- [docs/mitc4-shell-feast-eigen/implementation-verification.md](../../docs/mitc4-shell-feast-eigen/implementation-verification.md)
+
+이 Step의 직접 계약: [io-mapping.md#m3-원본-txt-grammar와-deterministic-value-projection](../../docs/mitc4-shell-feast-eigen/io-mapping.md#m3-원본-txt-grammar와-deterministic-value-projection), [io-mapping.md#m4-판정보고와-기존-static의-역할](../../docs/mitc4-shell-feast-eigen/io-mapping.md#m4-판정보고와-기존-static의-역할), [reference-model.md](../../docs/mitc4-shell-feast-eigen/reference-model.md), [../TOLERANCE.md](../../docs/mitc4-shell-feast-eigen/../TOLERANCE.md), [requirements-evidence.md#필수-회귀-포트폴리오와-identity](../../docs/mitc4-shell-feast-eigen/requirements-evidence.md#필수-회귀-포트폴리오와-identity), [numerical-review-cases.md#p4-ioreference운영-closure](../../docs/mitc4-shell-feast-eigen/numerical-review-cases.md#p4-ioreference운영-closure).
+논리 case의 전체 parameter/threshold/음성 inventory는 NR 원문과 [verification mapping](../../docs/mitc4-shell-feast-eigen/implementation-verification.md)을 함께 적용한다.
+
+## Owned paths
+
+다음 목록은 phase index `owned_paths`와 exact equality를 유지한다. 목록 밖 파일이 필요하면 보존하고 Coordinator에 반환한다. 다른 agent도 같은 worktree를 사용하므로 타인 변경을 되돌리지 않는다.
+
+```json
+[
+  "tests/reference/eigen_reference_comparison.h",
+  "tests/reference/eigen_reference_comparison.cpp",
+  "tests/reference/eigen_reference_comparison_test.cpp",
+  "tests/CMakeLists.txt",
+  "tests/reference/eigen_reference_cases_test.cpp",
+  "tests/reference/mitc4_eigen_static_regression_test.cpp",
+  "tests/integration/analysis/linear_frequency_procedure_test.cpp",
+  "docs/mitc4-shell-feast-eigen/implementation-report.md",
+  "docs/mitc4-shell-feast-eigen/build-test.md",
+  "docs/mitc4-shell-feast-eigen/reference-comparison.md",
+  "docs/mitc4-shell-feast-eigen/reference-comparison-detail.md",
+  "docs/mitc4-shell-feast-eigen/implementation-step7-evidence.md"
+]
+```
+
+## 같은 session의 behavior별 TDD
+
+각 소단위는 아래 순서로 RED→observed failure→minimal GREEN→focused VERIFY를 완료한다. 마지막 소단위 뒤 full VERIFY를 한 번 수행하고 등록 Stop의 정상 전체검증도 받는다. Missing API의 정확한 compile/link failure는 RED일 수 있으나 configure/dependency 오류는 RED가 아니다. 이미 통과한 test를 새 RED라고 보고하지 않는다.
+
+### 1. 원본 TXT Value-only deterministic comparator
+
+Symbols: `EigenReferenceComparison::Compare/WriteDeterministicJson; exact TXT parser and source-key projection`.
+
+**RED:** Test-local synthetic TXT/HDF5 fixture로 reordered rows/equalValue distinct IDs와 Freq token 변경을 허용하고 missing/extra/duplicate/malformed/BOM/NaN/Inf/wronglabel/step/quantity/unit/mass/backend/schema를 tolerance 이전 실패시킨다. 양수 singleton 1% RMS 경계/nextafter·5% row 경계/nextafter, rowpass-RMSfail, generic near-zero B 경계 및 S0 cases를 먼저 고정한다.
+
+**Minimal GREEN:** IO-M3 full-match grammar의 모든 nonempty TXT rows를 읽고 입력 sole source step/N을 authority로 연결한다. Official modes.eigenvalue만 추출하고 source content identity/path를 확인한다. Existing ReferenceTolerancePolicy::Evaluate를 10singleton family에 적용하며 policy source는 수정하지 않는다. Deterministic report는 raw r/f/e, source keys/family/S/branch/RMS/prechecks를 모두 기록한다. Diagnostic all-c, frequencies/vectors는 비교량이나 fallback이 아니다.
+
+**Focused VERIFY:** 아래 regex 중 해당 suite를 먼저 discovery하여 tests>0을 확인하고 같은 test를 재실행한다. Exact exit와 실패 이유를 behavior별로 기록한다.
+
+### 2. Fresh 10모드·static portfolio·반복 실행 및 최종 구현 evidence
+
+Symbols: `EigenReferenceCases.FreshInputUsesTenBlockingValueFamilies; EigenReferenceCases.ReplaysPersistentModesAndRepeatsDeterministically; Mitc4EigenStaticRegression.FreshApprovedPortfolio`.
+
+**RED:** 새 fresh-run harness에 invocation counter/identity corruption fixture를 먼저 추가해 stale HDF5 또는 다른 binary/source content의 결과를 거부하는 failure를 관찰한다. 이미 구현된 eigenvalue가 reference와 통과할 수 있다는 이유로 의도적인 물리 failure를 만들지 않는다. Tests는 고유 execution directory에 원본 bytes 복사→직접 FesaApplication 호출→HDF5 읽기를 요구하고 cache-only path는 failure로 만든다. 이후 실제 지정 reference 및 기존 static portfolio를 실행한다.
+
+**Minimal GREEN:** Reference 실행 wrapper와 evidence projection만 보완한다. 원본 SHA-256/bytes/mtime 전후 동일, copied input byte equality, actual run exit/duration, binary/library hash와 result/log timestamp/hash를 기록한다. 새 eigen은 같은binary/runtime/thread/input3runs에서 N10/n3125/nz625와 raw Value10singleton 비교·N벡터 residual 재현·C4 결정론을 검증한다. Static shell/shellNL/shellNL-meshfine fresh solve와 source-key Ublocking/URwarning/reactionreview 및 factor1 equilibrium을 기존 comparators로 평가한다. Canonical3 reports와 detail에 전 requirements 연결 및 full counts/exits/누락0를 기록하고 Physics/Release 판단은 남긴다.
+
+**Focused VERIFY:** 아래 regex 중 해당 suite를 먼저 discovery하여 tests>0을 확인하고 같은 test를 재실행한다. Exact exit와 실패 이유를 behavior별로 기록한다.
+
+## Focused 명령
+
+현재 `tests/CMakeLists.txt`에서 `fesa_tests`는 unit/integration/reference 세 executable을
+모두 의존하는 aggregate다. 이 Step의 새 `tests/reference/` 파일은
+`fesa_reference_tests`에 등록하며 아래 build는 이를 포함한다. Registration 누락은
+필수 신규 이름별 discovery 검사에서 실패로 처리하고 full build로 RED를 대체하지 않는다.
+
+Workspace root의 PowerShell에서 실행한다. 초기 missing API RED라면 build의 expected failure를 기록하고 production 구현 후 같은 명령을 다시 실행한다.
+
+```powershell
+cmake -S . -B .harness/build -A x64
+cmake --build .harness/build --config Debug --target fesa_tests
+ctest --test-dir .harness/build -C Debug -R '^(EigenReferenceComparison|ReferenceTolerancePolicy|EigenReferenceCases|Mitc4EigenStaticRegression|Mitc4S4Reference|NonlinearStaticReference|ShellSurfacePressureReference)\.' --show-only=json-v1
+ctest --test-dir .harness/build -C Debug -R '^(EigenReferenceComparison|ReferenceTolerancePolicy|EigenReferenceCases|Mitc4EigenStaticRegression|Mitc4S4Reference|NonlinearStaticReference|ShellSurfacePressureReference)\.' --output-on-failure
+```
+
+Configure exit는 항상0이어야 한다. GREEN에서는 위 모든 exit0, discovered selected tests>0, failures0이어야 한다. 각 호출의 `$LASTEXITCODE`를 즉시 기록하고 실패 뒤 후속 명령으로 덮어쓰지 않는다.
+
+
+### 필수 신규 test discovery inventory
+
+- `EigenReferenceCases.MfeC25FreshTenValueFamilies`
+- `EigenReferenceCases.MfeC27FreshAndRepeatedEvidence`
+- `Mitc4EigenStaticRegression.MfeC26FreshApprovedPortfolio`
+- `EigenReferenceComparison.MfeC25PrechecksAndToleranceBoundaries`
+
+위 이름 모두를 focused 및 full discovery JSON의 `tests[].name`에서 확인한다. Parameterized 전개가 필요하면 원 obligation→실제 discovered 이름을 evidence에 명시하고 모든 전개 case를 실행한다. 단지 selected count>0이거나 기존 suite만 존재하는 것은 실패다. V2의 해당 독립 oracle/mutation과 이 Step의 behavior assertions를 실제 구현해 각 결과를 기록한다.
+
+## Full VERIFY
+
+현재 실제 backend는 config absent→CMake/Visual Studio 18 2026/x64/`.harness/build`/Debug다. Dependency cache 준비는 [environment](../../docs/mitc4-shell-feast-eigen/implementation-environment.md)의 정확한 명령과 preflight를 따른다. Generator 변경이나 preset fallback을 임의로 하지 않는다.
+
+```powershell
+cmake -S . -B .harness/build -A x64
+if ($LASTEXITCODE -ne 0) { throw 'configure failed' }
+cmake --build .harness/build --config Debug
+if ($LASTEXITCODE -ne 0) { throw 'build failed' }
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+if ($LASTEXITCODE -ne 0) { throw 'discovery failed' }
+ctest --test-dir .harness/build -C Debug --output-on-failure
+if ($LASTEXITCODE -ne 0) { throw 'full CTest failed' }
+uv run --with pytest python -B -m pytest -v -rs
+if ($LASTEXITCODE -ne 0) { throw 'full pytest failed' }
+```
+
+전체 discovery의 test count와 실제 실행 count를 대조하고 skipped/missing/unobserved를 성공으로 합치지 않는다. 기존 target의 `/W4 /WX`를 유지하고 새 compiler/link warning0을 확인한다. 등록 Stop의 전체 검증은 그대로 수행되며 수동 hook 실행·state/reentry 조작으로 대체하지 않는다. Step 7에서 영향받는 C++ binary가 바뀌면 기존 reference helper의 cache 재사용 여부와 실제 solve 호출을 구분한다. 이 Step에서 최종 fresh portfolio를 완료한다.
+
+## Evidence와 종료
+
+- `docs/mitc4-shell-feast-eigen/implementation-report.md`
+- `docs/mitc4-shell-feast-eigen/build-test.md`
+- `docs/mitc4-shell-feast-eigen/reference-comparison.md`
+- `docs/mitc4-shell-feast-eigen/reference-comparison-detail.md`
+- `docs/mitc4-shell-feast-eigen/implementation-step7-evidence.md`
+
+이 Step의 evidence에는 Feature/owner/r2, exact owned changed paths, RED→GREEN 명령·actual exits·기간·핵심 수치, focused/full counts, MSVC/x64/Debug/dependency/runtime selection, warning 수, upstream case/requirement 연결, 미실행 및 residual risk를 기록한다. Raw logs는 Git ignored `.harness/build/mitc4-eigen-evidence/step7/`에 보존한다. 각 CTest 호출 직후 해당 `Testing/Temporary/LastTest.log`를 고유 RED/focused/full 이름으로 복사하여 이후 Stop 로그와 섞지 않는다. Binary/reference/result hash와 run freshness는 적용되는 경우 기록한다.
+
+
+보고서 작성 시점에는 마지막 registered Stop/Codex exit가 아직 발생하지 않을 수 있다. Implementation은 실제 완료된 manual 검증과 미관찰 Stop을 구분하고 미래 성공을 선기록하지 않는다. `completed` payload는 그 자체로 Stop 성공 증거가 아니다. Executor 종료 뒤 Coordinator가 raw output·등록 Hook evidence·actual exit를 management 문서에서 사후 감사한다. Specialist 보고서 본문은 Coordinator가 대신 수정하지 않는다.
+
+Manual AC가 성공하면 Executor가 허용한 `phases/mitc4-shell-feast-eigen/index.json`의 **현재 Step 7만** `status=completed`와 비어 있지 않은 `summary`를 기록한다. 구현/검증 실패는 `error/error_message`, 환경·필수 준비 차단은 `blocked/blocked_reason`이다. `owned_paths`, 이름/번호, 다른 Step/top index, timestamp, attempt_history는 수정하지 않는다. `step7-output.json`은 Executor 생성 기록이며 ignored 상태를 유지한다. 마지막 응답은 공통 handoff envelope다. Phase 전체 또는 workflow gate의 자기 승인은 하지 않는다.
+
+## 제외와 중단 조건
+
+Physics/formulation/I/O/tolerance/원본 reference·기존 feature 보고서 변경, 외부 solver, spectrum fitting, eigen 외부 vector/frequency/stress gate, sparse rank cutoff, sandbox 확대, retry-budget 변경, Git branch/commit/push/tag/release는 소유 범위 밖이다. 명백한 구현 결함은 이 exact scope 안에서 최소 수정한다. 계약 결함은 정확한 owner로 `return-upstream`, 실행 환경 실패는 actual command/exit와 함께 Coordinator로 반환한다. 동일 실패를 transport timeout으로 가장하거나 evidence를 지우고 재실행하지 않는다.