diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 6fcfdf5..879f0c9 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,50 +1,46 @@ # FESA Session Handoff -## 1. 문서 목적과 기준 +## 1. 목적과 기준 문서 -이 문서는 `deterministic-parallel-assembly` 완료 후 새 세션에서 -`result-contract-completion` Phase를 바로 시작하기 위한 인수인계 기록이다. -요구사항과 설계의 최종 기준은 다음 파일이다. +이 문서는 `beam-reference-qualification` 완료 후 새 세션에서 마지막 Phase 1 단계인 +`internal-release`를 시작하기 위한 인수인계 기록이다. 과거 phase의 구현 역사를 +반복하기보다 현재 기준선, 검증 결과, 남은 작업과 실행 순서를 제공한다. + +다음 문서를 우선 기준으로 사용한다. - `AGENTS.md` - `docs/PRD.md` - `docs/ARCHITECTURE.md` - `docs/ADR.md` - `docs/HARNESS.md` -- `docs/formulation/timoshenko-beam-3d.md` - `docs/HDF5_SCHEMA.md` -- `phases/result-contract-completion/index.json` -- `phases/result-contract-completion/step0.md`부터 `step2.md` +- `docs/ABAQUS_INPUT_SUBSET.md` +- `docs/formulation/timoshenko-beam-3d.md` +- `docs/VALIDATION.md` +- `phases/internal-release/index.json` +- `phases/internal-release/step0.md`부터 `step4.md` -내용이 충돌하면 위 기준 문서와 `phases/`의 현재 metadata를 우선한다. 이 문서는 -현재 구현, 검증 baseline, 다음 Phase에서 먼저 정렬해야 할 계약과 실행환경을 -보충한다. +내용이 충돌하면 `AGENTS.md`, PRD/ADR/아키텍처, 완료된 phase metadata와 실제 +테스트를 우선한다. 특히 `internal-release`의 기존 Step 0과 Step 4에 남아 있는 +reference 범위 설명은 4절의 최신 계약으로 바로잡은 뒤 release evidence에 사용한다. -## 2. 현재 저장소와 Phase 상태 +## 2. Git과 Phase 상태 -2026-08-02 확인 기준: +2026-08-03 기준 구현 상태는 다음과 같다. - 기준 브랜치: `dev` -- 이 HANDOFF 갱신 직전 구현 HEAD: - `7d52247d6c6180ac4f4dab2e6ecb0ee1be2608d0` -- 갱신 직전 `dev`는 `origin/dev`보다 9개 commit 앞서 있었고 작업 트리는 clean이었다. -- `feat-deterministic-parallel-assembly`는 `dev`에 fast-forward 병합한 뒤 삭제했다. -- 완료 Phase: - - `solver-bootstrap` - - `domain-and-input-skeleton` - - `fem-and-beam-kernel` - - `equation-and-linear-solve` - - `results-and-pipeline` - - `abaqus-subset-completion` - - `deterministic-parallel-assembly` -- 다음 Phase: `result-contract-completion` -- 다음 Step: Step 0 `beam-element-end-recovery` -- `result-contract-completion`의 Step 0~2는 모두 pending이다. -- 후속 Phase `beam-reference-qualification`과 `internal-release`도 pending이다. +- 이 문서 갱신 직전 구현 HEAD: `6bc7cc3adadded6f1a2a0ed45449b2264c0f7a4e` +- `feat-beam-reference-qualification`은 `dev`에 fast-forward 병합된 뒤 로컬에서 + 삭제됐다. +- `internal-release`를 제외한 `phases/index.json`의 모든 phase가 `completed`다. +- 다음 Phase: `internal-release` +- 다음 Step: Step 0 `release-checklist` +- Step 0부터 Step 4까지 모두 `pending`이다. +- 이 문서의 갱신은 구현 기준선 다음의 docs-only commit이다. -이 문서는 위 9개 구현/phase commit 다음 commit으로 `dev`에 기록하고 모두 -`origin/dev`에 push한다. 새 세션에서는 reset, rebase 또는 force push로 상태를 -맞추지 말고 먼저 실제 동기화 상태를 확인한다. +새 세션에서는 기록된 hash를 강제로 맞추지 말고 로컬과 원격의 실제 상태를 먼저 +확인한다. 이 HANDOFF commit이 push된 뒤에는 `dev`와 `origin/dev`가 같은 commit을 +가리켜야 한다. ```powershell git switch dev @@ -54,248 +50,185 @@ git rev-parse origin/dev git rev-list --left-right --count origin/dev...dev ``` -이번에 함께 push할 선행 commit은 다음과 같다. +reset, rebase 또는 force push로 차이를 숨기지 않는다. 예상하지 못한 변경이 있으면 +소유자를 확인하고 보존한다. -```text -40a7e6c feat(deterministic-parallel-assembly): step 0 — canonical-contribution-order -b9bb439 chore(deterministic-parallel-assembly): step 0 output -6c2e1f3 feat(deterministic-parallel-assembly): step 1 — tbb-element-evaluation -dc6baed chore(deterministic-parallel-assembly): step 1 output -127286c feat(deterministic-parallel-assembly): step 2 — thread-count-determinism -6ee51a8 chore(deterministic-parallel-assembly): step 2 output -6ad9f3c chore(deterministic-parallel-assembly): mark phase completed -ac8d24a test(assembly): cover deterministic kernel failures -7d52247 fix(assembly): stage benchmark TBB runtime -``` +## 3. 완료된 Phase 1 기준선 -## 3. 완료된 deterministic parallel assembly +현재 production 경로는 다음 기능을 제공한다. -Phase metadata는 `phases/deterministic-parallel-assembly/index.json`에 기록되어 -있으며 Step 0~2가 모두 completed다. +- Abaqus `.inp` 제한 부분집합의 flat/orphan mesh 또는 좌표변환이 없는 단일 + Part/Assembly/Instance 모델 파싱과 semantic validation +- 2절점 3D Isoparametric Timoshenko Beam, 등방성 선형 탄성, 일반 단면, + `*BOUNDARY`, `*CLOAD`, 단일 선형 정적 Step +- MSVC v145, Intel oneAPI MKL PARDISO와 TBB를 사용하는 Windows x64 해석 경로 +- canonical contribution ordering에 기반한 결정론적 병렬 요소 평가와 조립 +- 원래 full equation에서 변위, 반력과 평형을 복구하는 선형 정적 해석 +- 두 요소 끝의 section strain, section force, centroid/recovery-point `Sxx` 회복 +- node/element provenance, component와 좌표계 metadata를 포함한 완전한 + `ResultDatabase` +- 입력 원본 없이 model, analysis와 결과를 재구성할 수 있는 HDF5 schema `2.0.0` +- 변위, 반력, 요소 단면력용 Abaqus CSV adapter와 component별 상관성 보고 CLI -주요 결과: +결과 계약과 Beam reference phase의 세부 완료 기록은 다음 파일에 있다. -- `MatrixContribution`의 canonical key를 - `(row, column, element, local_order)`로 고정했다. -- upper-triangle CSR pattern과 값을 한 번의 deterministic serial merge로 만든다. -- oneTBB는 Beam 요소별 `compute_beam3d2` 평가에만 사용한다. -- worker는 요소별 로컬 contribution을 만들고 shared CSR values에 쓰지 않는다. -- `AssemblyOptions.max_threads`와 `grain_size`는 0을 거부한다. -- element storage order와 external label 순열에 관계없이 기존 serial oracle의 - `EntityOrigin` 순서를 보존하도록 canonical rank를 contribution의 `ElementId`에 - 사용한다. -- 여러 Beam kernel failure가 동시에 발생해도 canonical element origin상 첫 오류를 - 반환한다. 해당 독립 review 보완은 mutation test로 RED를 확인한 뒤 추가했다. -- thread count 1, 2, 16에서 10회 반복하며 CSR 구조/값, RHS, displacement와 - reaction의 bit pattern이 동일함을 검증한다. -- `fesa_assembly_benchmark`는 production serial/parallel API를 사용하고 시간과 - element count만 출력한다. speedup은 correctness 조건이 아니다. -- benchmark target의 output directory에 imported `TBB::tbb` runtime DLL을 - post-build로 복사하므로 새 셸의 PATH에 TBB가 없어도 정확한 exe 경로로 실행된다. - -관련 파일: - -- `include/fesa/assembly/contribution.hpp` -- `include/fesa/assembly/assembler.hpp` -- `src/fesa/assembly/contribution.cpp` -- `src/fesa/assembly/parallel_assembler.cpp` -- `src/fesa/assembly/serial_assembler.cpp` -- `tests/unit/assembly/serial_assembler_test.cpp` -- `tests/unit/assembly/parallel_assembler_test.cpp` -- `tests/integration/assembly/thread_count_determinism_test.cpp` -- `tests/performance/assembly_benchmark.cpp` - -유지할 핵심 경계: - -- `assemble_serial`은 계속 bitwise oracle이다. -- TBB task가 끝난 후에만 solver를 호출한다. -- TBB type은 `core`, `model`, `fem`, `elements` public contract에 노출하지 않는다. -- scheduling 순서가 contribution 합산 순서나 오류 선택을 결정하면 안 된다. -- `LinearStaticAnalysis`는 현재도 `assemble_serial`을 호출한다. 다음 Phase 요구사항에 - 없는 parallel backend 선택 기능을 끼워 넣지 않는다. - -## 4. 현재 결과·HDF5 baseline과 남은 간극 - -`results-and-pipeline`에서 최소 수직 파이프라인은 완성되어 있다. - -- `ResultDatabase -> ResultStep -> ResultFrame -> NodalFrame` semantic model -- serial assembly, essential BC, PARDISO, full displacement reconstruction과 - `r=Ku-f` 반력 복구를 조율하는 `LinearStaticAnalysis` -- all-constrained case의 order-0 PARDISO 우회 -- schema `1.0.0` HDF5 writer와 public reader -- parser부터 HDF5 output까지 연결하는 `run_solver`와 `fesa solve` - -현재 구현의 정확한 한계: - -- `ResultFrame`은 `step_time`, nodal displacement/reaction, diagnostics만 가진다. -- node/element `EntityOrigin`, field 좌표계, component label/order가 semantic result에 - 명시되어 있지 않다. -- Beam section strain/resultant, local frame, centroid/recovery-point stress가 없다. -- `LinearStaticAnalysis`는 nodal result만 채우며 element recovery를 호출하지 않는다. -- HDF5 schema `1.0.0`은 node 좌표·origin, Beam connectivity/section ID, 적용된 - shear area/source와 nodal result만 저장한다. -- HDF5 reader의 model은 adapter 전용 `Hdf5ModelSnapshot`이며 완전한 model/analysis - 재구성 계약이 아니다. -- material 전체 속성, sets, section 전체 속성/orientation/recovery points, - step BC/load/solver settings, element result와 diagnostics는 파일에 없다. -- writer는 non-empty frame diagnostics를 - `hdf5.unsupported_result_diagnostics`로 거부한다. - -관련 파일: - -- `include/fesa/results/result_database.hpp` -- `src/fesa/results/result_database.cpp` -- `include/fesa/analysis/linear_static_analysis.hpp` -- `src/fesa/analysis/linear_static_analysis.cpp` -- `include/fesa/io/hdf5/writer.hpp` -- `src/fesa/io/hdf5/writer.cpp` +- `phases/result-contract-completion/index.json` +- `phases/beam-reference-qualification/index.json` - `docs/HDF5_SCHEMA.md` -- `tests/unit/results/result_database_test.cpp` -- `tests/unit/analysis/linear_static_analysis_test.cpp` -- `tests/integration/io/hdf5_results_test.cpp` -- `tests/integration/pipeline/minimal_cantilever_test.cpp` +- `docs/VALIDATION.md` -이 간극을 `result-contract-completion`에서만 필요한 만큼 채운다. +`internal-release`에서는 위 solver 계약을 다시 설계하지 않는다. 설치, clean consumer, +scale measurement와 release evidence에 필요한 최소 변경만 수행한다. -## 5. 다음 Phase 목표와 Step 순서 +## 4. 검증 상태와 남은 제한 -### Step 0 - beam-element-end-recovery +### 4.1 이중 검증 gate -- 두 요소 끝의 section strain과 section resultant를 계산한다. -- strain 순서는 - `(epsilon, gamma_y, gamma_z, kappa_x, kappa_y, kappa_z)`, force 순서는 - `(N, Vy, Vz, T, My, Mz)`로 고정한다. -- centroid stress는 `N/A`, recovery point `(y,z)`의 stress는 axial+bending - `sigma_xx`만 계산한다. -- 순수 축, 비틀림, 각 축 굽힘, 이축 굽힘, 양 끝 부호와 입력 recovery-point 순서를 - hand calculation으로 먼저 고정한다. -- stiffness와 동일한 `BeamFrame`, DOF, 회전 및 부호 convention을 재사용한다. +`docs/VALIDATION.md`가 검증 결과의 단일 상세 보고서다. -Focused acceptance: +- Gate A — FESA 정식화 적합성: **PASS** +- Gate B — Abaqus 결과 상관성: **EVALUABLE** -```powershell -cmake --build --preset windows-debug -ctest --preset windows-debug -R "BeamRecovery|CentroidStress|SectionForce" --output-on-failure -ctest --preset windows-debug --output-on-failure -``` +Gate A는 해석해, strain energy, 강체 mode, 회전 불변성, 평형과 결정성을 엄격한 +tolerance로 검증한다. Gate B는 Abaqus B31과 FESA 정식화의 차이를 인정하고 +component별 RMSE와 Relative L2를 보고한다. Gate B의 `EVALUABLE`은 모든 요청 +entity/component가 유일하게 매칭되고 metric이 유한하다는 뜻이며, 임의의 상관성 +pass/fail threshold를 통과했다는 뜻은 아니다. -### Step 1 - complete-result-contract +현재 cantilever reference의 주요 Relative L2는 다음과 같다. -- `BeamElementFrame`에 element ID/origin, local frame과 두 끝 - `BeamSectionResult`를 저장한다. -- `ResultFrame`에 `ElementFrame`을 추가한다. -- node/element provenance, field 좌표계와 component label/order를 semantic contract에 - 명시한다. -- duplicate element/end node, wrong connectivity, nonfinite value와 mismatched - recovery-point count를 validation에서 거부한다. -- `LinearStaticAnalysis`가 production Beam recovery API를 호출해 element result를 - 채운다. recovery 수식을 analysis에 복제하지 않는다. +| 결과 | Component | Relative L2 | +|---|---|---:| +| displacement | `Uz` | `0.0022349969291714038` | +| displacement | `Ry` | `0.0000010416581667076092` | +| reaction | `RFz` | `4.4393520322089023e-13` | +| reaction | `RMy` | `2.591919334788851e-13` | +| internal force | `Vz` | `2.7107472798172426e-13` | +| internal force | `My` | `0.082541022764834646` | -Focused acceptance: +18개 전체 component의 count, RMSE와 Relative L2는 `docs/VALIDATION.md`를 사용한다. -```powershell -cmake --build --preset windows-debug -ctest --preset windows-debug -R "CompleteResultContract|ElementFrame" --output-on-failure -ctest --preset windows-debug --output-on-failure -``` +### 4.2 Reference 모델과 축 매핑 -### Step 2 - self-contained-hdf5 +- Abaqus provenance는 `reference/cantilever beam/cantilever beam.inp`와 세 CSV다. +- Abaqus 원본 모델의 `SCF=0.25`는 보존한다. +- FESA projection은 `reference/cantilever beam/cantilever beam fesa.inp`이며 다른 + 의미 입력을 유지하고 `SCF=0`을 사용한다. +- FESA에 Abaqus SCF 보정이나 결과 맞춤 계수를 추가하지 않는다. -- 구현보다 먼저 `docs/HDF5_SCHEMA.md`에 새 version과 모든 dataset의 type, rank, - shape, component/coordinate attributes를 확정한다. -- 파일 하나로 model, single-step analysis settings와 모든 Phase 1 result를 - 재구성한다. -- model에는 coordinates/connectivity/origin, sets, materials, section 전체 속성, - orientation, recovery points와 적용 shear 값/source를 포함한다. -- analysis에는 step, BC, load와 solver settings를 포함한다. -- results에는 nodal displacement/reaction, Beam local frame, 두 끝 strain/force, - centroid/recovery-point `Sxx`와 diagnostics를 포함한다. -- public reader round trip과 `h5ls`로 구조를 독립 검증한다. +요소력 CSV는 다음 순서로 매핑한다. -Focused acceptance: +| FESA | Abaqus CSV | +|---|---| +| `N` | `SF1` | +| `Vy` | `SF3` | +| `Vz` | `SF2` | +| `T` | `SM3` | +| `My` | `SM1` | +| `Mz` | `SM2` | -```powershell -cmake --build --preset windows-debug -ctest --preset windows-debug -R SelfContainedHdf5 --output-on-failure -h5ls -r .\out\build\windows-debug\Testing\Temporary\fesa-self-contained.h5 -ctest --preset windows-debug --output-on-failure -``` +### 4.3 아직 완료되지 않은 검증 -## 6. 구현 전에 정렬할 설계점 +- 실제 Abaqus 결과로 검증된 물리량은 변위, 반력과 요소 단면력이다. +- Abaqus 도심 응력 CSV는 제공되지 않았다. `StressCsv`는 synthetic fixture로 schema와 + entity mapping만 검증했으며 응력은 **not yet Abaqus-qualified**다. +- synthetic internal-force fixture도 adapter 단위 검증에 계속 사용하지만, 요소 + 단면력 자체는 별도의 실제 Abaqus golden CSV와 상관성 비교가 완료됐다. +- 내부 배포용 Release build, install tree, clean consumer smoke test와 약 100,000 DOF + 측정은 아직 실행되지 않았다. 증거 없이 완료 표시하지 않는다. -아래는 범위 확장이 아니라 Step 문서와 현재 타입 사이에서 테스트 전에 명시적으로 -결정해야 할 최소 계약이다. +### 4.4 `internal-release` Step 문서의 계약 불일치 -1. `end_node`의 소유권 - - Step 0 초안의 `BeamSectionResult`에는 `NodeId end_node`가 있지만 제시된 - `recover_beam3d2(const Beam3D2Input&, ...)` 입력에는 Node ID가 없다. - - 가짜 ID를 만들지 않는다. recovery API가 node IDs를 받게 할지, kernel은 - end ordinal/`xi`만 반환하고 orchestration이 실제 NodeId를 붙일지 최소 설계를 - 정한 뒤 테스트로 고정한다. +`phases/internal-release/step0.md`와 `step4.md`에는 beam reference phase 이전의 문구가 +남아 있다. -2. 끝점 strain/resultant와 부호 - - `docs/formulation/timoshenko-beam-3d.md`의 국부 DOF, shear strain, curvature와 - `sigma_xx=E(epsilon+z*kappa_y-y*kappa_z)`를 기준으로 한다. - - section resultant의 양의 방향과 element nodal resisting-force 방향을 혼동하지 - 않는다. 끝값에 임의 절댓값이나 후처리 sign flip을 적용하지 않는다. +- “현재 Abaqus displacement/reaction comparison”은 변위·반력·요소 단면력 + correlation으로 갱신해야 한다. +- “내력·응력은 synthetic coverage”라는 묶음 표현은 요소 단면력과 응력을 분리해야 + 한다. 요소 단면력은 real golden correlation과 synthetic adapter coverage가 모두 + 있고, 응력만 synthetic adapter coverage다. -3. Recovery point 계약 - - `BeamSection.recovery_points`의 `(y,z)` 순서와 입력 순서를 보존한다. - - 빈 목록의 유효성, 두 끝의 expected count와 nonfinite coordinate/result 처리를 - result validation 및 round-trip test에서 명시한다. - - 단면 형상 정보가 없으므로 point shear/torsional stress를 추정하지 않는다. +새 세션은 Harness 실행 전에 이 두 Step 문서와 관련 checklist 문구를 현재 +`docs/PRD.md` 8절 및 `docs/VALIDATION.md`와 일치시켜야 한다. 이 정렬은 검증 범위의 +확장이 아니라 이미 완료된 증거를 정확히 기술하는 작업이다. -4. Result provenance와 component metadata - - semantic result는 Abaqus/CSV/HDF5 명칭이나 handle에 의존하지 않는다. - - node와 element origin, local/global coordinate system, component ordering을 - 중복된 문자열 상수로 흩뜨리지 않을 최소 표현을 선택한다. +## 5. 다음 Phase: `internal-release` -5. HDF5 version과 reader 반환 계약 - - 현재 `1.0.0`은 required object의 의미/형상/type을 같은 major에서 바꾸지 않는 - 계약이다. 완전한 schema를 무버전으로 덮어쓰지 말고 version 정책을 문서와 - reader/writer test에 함께 반영한다. - - public reader가 `Domain` 자체를 반환할지 완전한 serialization snapshot을 - 반환할지는 아키텍처 경계를 확인해 결정하되, 원본 `.inp` 경로에 기대지 않고 - 모든 요구 항목을 재구성할 수 있어야 한다. +Phase metadata는 `phases/internal-release/index.json`에 있다. Step은 순서대로 실행한다. -6. Diagnostics와 analysis settings - - 현재 diagnostics는 semantic frame에 있지만 HDF5 writer가 non-empty 값을 - 거부한다. stage/severity/code/message/source의 손실 없는 저장 계약을 먼저 - 정한다. - - solver settings는 실제 Phase 1 실행 설정만 저장한다. 사용하지 않는 미래 - backend/history/dynamic 설정을 빈 구조로 추가하지 않는다. +### Step 0 — `release-checklist` -## 7. 아키텍처와 범위 경계 +- `docs/BUILDING.md`, `docs/INPUT_FORMAT.md`, `docs/RELEASE_CHECKLIST.md`를 작성한다. +- PRD 8절의 각 내부 배포 기준에 고유 checklist ID를 부여한다. +- 실제 target, preset, example과 evidence command를 CMake에서 재확인한다. +- 미실행 Release/install/benchmark 항목을 완료 표시하지 않는다. +- 4.4절의 stale reference 문구를 먼저 바로잡는다. -- `core`, `model`, `fem`, `elements`는 Abaqus, HDF5, MKL 및 TBB API에 의존하지 않는다. -- Beam kernel에는 Abaqus output column 이름이나 CSV-specific field를 넣지 않는다. -- `ResultDatabase`에는 HDF5 object/handle 또는 serialization 전용 type을 노출하지 +### Step 1 — `cmake-install-package` + +- `cmake --install`로 내부 배포용 install tree를 만든다. +- CLI, `fesa_core`, public headers, CMake package config, example, schema/input/validation + 문서와 runtime DLL inventory를 포함한다. +- install config에 absolute build path가 남는 실패 검사를 먼저 작성한다. +- installer, registry write, 외부 dependency 다운로드와 public ABI 약속은 범위 밖이다. + +### Step 2 — `install-tree-smoke-test` + +- source/build tree를 참조하지 않는 consumer configure/link test를 만든다. +- 설치된 CLI의 `--version`, example solve와 생성 HDF5 open을 검증한다. +- 개발 PATH의 `fesa.exe`나 source include fallback으로 결함을 숨기지 않는다. + +### Step 3 — `phase1-scale-benchmark` + +- 약 100,000 DOF Beam chain에서 generation/parsing, assembly, PARDISO solve, + recovery와 HDF5 write 시간을 분리해 측정한다. +- 재현 가능한 Windows memory metric, thread/solver 설정과 실제 DOF 수를 기록한다. +- finite result, 평형과 정상 종료는 검사하되 임의 시간·speedup 기준은 만들지 않는다. + +### Step 4 — `release-evidence-gate` + +- Debug와 Release configure/build/test를 새로 실행한다. +- test count가 0이 아닌지 확인한다. +- Harness pytest, reference, determinism, HDF5 inspection, install-tree smoke test와 scale + benchmark 증거를 checklist ID에 연결한다. +- 모든 수용 조건에 현재 실행 증거가 있을 때만 Step과 Phase를 `completed`로 바꾼다. +- 실패나 미실행 항목이 있으면 정확한 blocker를 남기고 release 완료를 선언하지 않는다. + +## 6. 유지해야 할 경계 + +- C++20, Visual Studio 2026 MSVC v145와 Windows x64 기준을 유지한다. +- `core`, `model`, `fem`, `elements`에 Abaqus, MKL, TBB 또는 HDF5 API를 노출하지 않는다. -- HDF5 resource는 adapter의 move-only RAII wrapper 내부에 둔다. -- DofManager가 DOF와 equation mapping을 계속 단독 소유한다. -- analysis는 production recovery API를 조율하고 수식을 복제하지 않는다. -- 기존 parser/model validation/solver 경로를 test helper로 우회하지 않는다. -- 실제 두 번째 구현이 생기기 전에는 generic registry나 backend hierarchy를 만들지 +- solver semantic model과 result contract에 installer 또는 serialization 전용 타입을 + 추가하지 않는다. +- dependency는 개발 환경에 사전 설치된 버전을 사용하며 package 중 다운로드하지 않는다. -- 이번 Phase에서 Abaqus CSV mapping, golden comparison와 물리량별 tolerance를 - 선행하지 않는다. 이는 `beam-reference-qualification` 범위다. -- installer, Release package와 validation report를 선행하지 않는다. 이는 - `internal-release` 범위다. +- install tree는 source/build tree의 절대경로에 의존하지 않아야 한다. +- Debug와 Release artifact/runtime을 혼합하지 않는다. +- FESA는 단위 변환을 수행하지 않는다. +- performance 수치를 correctness gate로 바꾸지 않는다. +- stress를 Abaqus-qualified로 표현하지 않는다. +- 테스트를 disable하거나 제외해 release evidence를 만들지 않는다. +- 사용자가 명시적으로 요청하지 않은 phase 실행에서는 `--push`를 사용하지 않는다. -## 8. 검증된 baseline과 개발환경 +## 7. 검증 기준선과 개발환경 -2026-08-02 기준 도구와 dependency: +### 7.1 마지막 확인 결과 -- CMake 4.4.0 -- MSBuild 18.8.2.30814 -- Visual Studio 2026 MSVC v145, Windows x64 -- codex-cli 0.146.0 -- Intel oneAPI MKL/TBB 2026.1 -- HDF5 2.1.1 -- GoogleTest 1.17.0, v145 x64 CRT build +2026-08-03의 beam reference qualification 완료 및 `dev` 병합 후 다음을 확인했다. -새 PowerShell 세션에서 configure 또는 Harness 실행 전에 설정한다. 절대경로를 -tracked CMake/Preset에 넣지 않는다. +- `cmake --build --preset windows-debug`: 성공, 새 MSVC warning 없음 +- `ctest --preset windows-debug --output-on-failure`: 68/68 통과 +- `uv run --with pytest python -m pytest -v -rs`: 20/20 통과 +- thread `{1,2,16}`에서 10회 반복한 조립/해석 결과: bitwise 동일 + +이 수치는 새 세션이 유지해야 할 Debug baseline이다. Release와 install-tree 결과로 +확대 해석하지 않는다. + +### 7.2 Package 설정 + +새 PowerShell 세션에서 configure 전에 현재 설치 위치를 확인한다. tracked preset이나 +CMake 파일에 사용자별 절대경로를 넣지 않는다. ```powershell $env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl" @@ -309,148 +242,83 @@ Test-Path "$env:HDF5_DIR\hdf5-config.cmake" Test-Path "$env:GTest_DIR\GTestConfig.cmake" ``` -기본 검증 명령: - -```powershell -cmake --build --preset windows-debug -ctest --preset windows-debug --output-on-failure -uv run --with pytest python -m pytest -v -rs -.\out\build\windows-debug\Debug\fesa_assembly_benchmark.exe -``` - -HANDOFF 갱신 직전 확인한 baseline: - -- MSVC Debug build 성공, 새 warning 없음 -- CTest 54개 중 54개 성공 -- Harness pytest 20개 중 20개 성공; 0-test 성공이 아님 -- phase focused CTest 5개 모두 성공 -- benchmark 예시: - `elements=1000 serial_ms=488.602 parallel_ms=287.849 parallel_threads=16` - (시간과 speedup은 환경 의존적이며 pass 조건이 아니다.) - -CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저 -다음을 실행한다. +네 경로가 모두 유효한 같은 셸에서 preset을 실행한다. cache가 없거나 package 위치가 +변경됐을 때만 `--fresh` configure를 사용한다. ```powershell cmake --fresh --preset windows-debug +cmake --build --preset windows-debug +ctest --preset windows-debug --output-on-failure +uv run --with pytest python -m pytest -v -rs ``` -`h5ls` 직접 실행에는 HDF5 DLL과 Intel `libmmd.dll`이 모두 필요하다. 시스템 PATH는 -영구 변경하지 말고 현재 셸에만 추가한다. +Release evidence는 `internal-release` Step에서 새로 생성한다. ```powershell -$env:PATH = @( - "C:\Program Files\HDF_Group\HDF5\2.1.1\bin", - "C:\Program Files (x86)\Intel\oneAPI\2026.1\bin", - $env:PATH -) -join ";" -h5ls --version +cmake --preset windows-release +cmake --build --preset windows-release +ctest --preset windows-release --output-on-failure ``` -## 9. Harness child 환경 주의사항 +## 8. Harness 주의사항 -이전 Phase의 최초 Harness 실행에서 child가 WindowsApps PowerShell을 시작할 때 -access denied가 발생했고, 일부 재시도 build process가 겹치며 timeout과 stale -blocked metadata가 잠시 남았다. 최종적으로 모든 Step output의 `exitCode`는 0이고 -phase metadata도 completed로 정리되었다. - -현재 `C:\Users\baram\.codex\config.toml`은 원래 값인 -`[windows] sandbox = "elevated"`로 복원되어 있음을 2026-08-02에 재확인했다. -다음 Phase에서는 먼저 표준 실행을 시도하고 같은 문제가 재현될 때만 아래 임시 -workaround를 적용한다. - -- 기존 `scripts/execute.py`, child Codex, CMake/MSBuild process가 완전히 종료됐는지 - 확인해 중복 executor를 만들지 않는다. -- global config의 원래 값을 기록한 뒤 Harness 실행 동안만 sandbox를 - `unelevated`로 바꾼다. -- PATH 앞에는 standalone Codex와 Windows PowerShell 5.1을 두고 WindowsApps 및 - OpenAI Codex app-bin entry를 제거한다. -- 성공/실패와 관계없이 종료 즉시 config를 `elevated`로 복원하고 다시 읽어 확인한다. +표준 실행 명령은 다음과 같다. ```powershell -$codexReleaseBin = "C:\Users\baram\.codex\packages\standalone\releases\0.146.0-x86_64-pc-windows-msvc\bin" -$windowsPowerShell = "$env:SystemRoot\System32\WindowsPowerShell\v1.0" -$filteredPath = $env:PATH -split ";" | Where-Object { - $_ -and - $_ -ne $codexReleaseBin -and - $_ -ne $windowsPowerShell -and - $_ -notmatch "WindowsApps" -and - $_ -notmatch "\\OpenAI\\Codex\\bin$" -} -$env:PATH = (@($codexReleaseBin, $windowsPowerShell) + $filteredPath) -join ";" - -(Get-Command codex).Source -(Get-Command powershell).Source +python scripts/execute.py internal-release ``` -설치 버전이나 경로가 바뀌었다면 위 절대경로를 그대로 사용하지 말고 실제 standalone -release와 `codex-resources` 존재를 먼저 확인한다. 사용자 profile 전체나 drive root를 -`--codex-add-dir`로 허용하지 않는다. +이전 beam reference phase에서 Harness child가 WindowsApps PowerShell을 시작하지 못해 +`CreateProcessAsUserW` 오류가 반복됐다. 동일 저장소와 preset에서 직접 실행한 수용 +명령은 성공했고, `stepN-output.json`에는 child 환경 blocker와 직접 실행 증거를 +구분해 기록했다. -## 10. 새 세션 시작 절차 +새 세션에서는 다음 원칙을 지킨다. -먼저 이 문서와 다음 파일을 읽는다. +1. 먼저 표준 Harness 실행을 시도한다. +2. 같은 child shell 오류가 발생하면 중복 executor를 시작하지 말고 남은 process를 + 확인한다. +3. 직접 실행한 명령과 Harness 실행 결과를 혼동하지 않고 metadata에 사실대로 적는다. +4. 사용자 profile이나 drive root를 `--codex-add-dir`로 허용하지 않는다. +5. global Codex 설정을 임시 변경했다면 원래 값을 기록하고 종료 즉시 복원·재확인한다. +6. 사용자가 push를 명시하지 않은 phase 실행에는 `--push`를 추가하지 않는다. -```text -phases/result-contract-completion/index.json -phases/result-contract-completion/step0.md -phases/result-contract-completion/step1.md -phases/result-contract-completion/step2.md -docs/formulation/timoshenko-beam-3d.md -docs/HDF5_SCHEMA.md -include/fesa/elements/beam/beam3d2.hpp -include/fesa/model/beam_section.hpp -include/fesa/results/result_database.hpp -include/fesa/io/hdf5/writer.hpp -src/fesa/elements/beam/beam3d2.cpp -src/fesa/results/result_database.cpp -src/fesa/analysis/linear_static_analysis.cpp -src/fesa/io/hdf5/writer.cpp -``` +## 9. 새 세션 시작 순서 -그 다음 Git/package 상태와 8절 baseline을 재검증하고 다음을 실행한다. +1. `AGENTS.md`와 이 문서를 읽는다. +2. `docs/PRD.md` 8절, `docs/VALIDATION.md`, `phases/internal-release/index.json`과 + Step 0~4를 읽는다. +3. Git 상태와 `dev == origin/dev`를 확인한다. +4. 4.4절의 Step 0/4 reference 범위 문구를 최신 계약에 맞춘다. +5. Debug baseline을 새로 실행한다. +6. Step 0의 release 문서와 checklist 요구조건을 먼저 테스트 가능한 형태로 고정한다. +7. 다음 명령으로 Phase를 실행한다. ```powershell -python scripts/execute.py result-contract-completion +python scripts/execute.py internal-release ``` -executor는 feature branch를 생성하거나 checkout하고 Step 상태와 -`stepN-output.json`을 기록한다. 사용자가 명시적으로 요청하지 않은 한 `--push`를 -사용하지 않는다. +각 Step에서는 실패하는 검사 또는 미충족 evidence를 먼저 확인하고, 최소 변경으로 +수용 조건을 만족시킨 뒤 focused test와 전체 test를 실행한다. Step output과 phase +metadata는 실제 명령 결과를 그대로 반영한다. -각 Step은 다음 순서를 지킨다. +## 10. `internal-release` 완료 조건 -1. Step 파일의 필수 문서와 현재 구현을 모두 읽는다. -2. 6절의 모호한 계약을 구현 전에 명시하고 focused test로 고정한다. -3. hand-calculated/unit/integration test가 예상한 이유로 실패함을 먼저 확인한다. -4. 테스트를 통과시키는 최소 production code만 구현한다. -5. focused CTest, 전체 CTest와 Harness pytest를 실행한다. -6. Step 2에서는 public reader와 정확한 `h5ls -r` 명령으로 파일 구조를 확인한다. -7. Step summary/output metadata와 실제 결과를 대조한다. -8. Phase 종료 전 결과 부호, provenance, schema completeness, adapter 경계와 - round-trip 손실 여부를 독립 review한다. +- `phases/internal-release/index.json`의 Step 0~4가 모두 `completed` +- `phases/index.json`의 `internal-release`가 `completed` +- PRD 8절의 모든 기준이 고유 checklist ID와 실제 증거에 연결됨 +- Debug/Release build에 새 MSVC warning이 없음 +- Debug/Release CTest와 Harness pytest가 0개가 아닌 상태로 모두 통과 +- `cmake --install` 결과에 요구 binary/library/header/document/example/runtime + inventory가 포함됨 +- source/build tree를 숨긴 install consumer와 CLI/HDF5 smoke test 통과 +- 약 100,000 DOF benchmark의 correctness, stage time, memory와 환경 기록 완료 +- Gate A PASS와 Gate B EVALUABLE의 의미 및 Abaqus stress 제한을 release 문서가 + 정확히 유지함 +- 실패하거나 미실행인 증거가 없는 경우에만 내부 배포 완료 선언 -## 11. 다음 Phase 완료 조건 +새 세션의 권장 첫 요청은 다음과 같다. -- `phases/result-contract-completion/index.json`의 Step 0~2가 모두 completed -- `phases/index.json`에서 `result-contract-completion`이 completed -- pure axial/torsion/bending/biaxial recovery의 값·끝 부호·point 순서 검증 -- section strain/resultant와 centroid/recovery-point `Sxx`의 명시적 component 및 - coordinate contract -- Beam element result의 ID/origin/connectivity/local frame 보존과 validation -- `LinearStaticAnalysis`가 production recovery로 complete `ResultDatabase` 생성 -- 새 version의 HDF5 하나만으로 model, analysis settings, nodal/element results와 - diagnostics 재구성 -- public reader round trip과 `h5ls -r` 구조 검증 -- focused test와 전체 CTest 통과 -- Harness pytest가 0개가 아닌 상태로 전체 통과 -- 새 MSVC warning 없음 -- 독립 review의 Critical/Important finding 해결 -- Abaqus golden/tolerance나 internal release 범위를 선행하지 않음 -- 사용자 요청 없이 원격 push 또는 `dev` 병합을 수행하지 않음 - -새 세션의 권장 첫 요청: - -> `docs/HANDOFF.md`와 `result-contract-completion`의 index/step0~2를 읽고 현재 -> `dev` baseline, Beam recovery의 미결 계약과 Harness child 실행 조건을 확인한 뒤 -> `result-contract-completion` Phase를 시작해주세요. +> `docs/HANDOFF.md`와 `internal-release`의 index/step0~4를 읽고 현재 `dev` +> baseline과 beam reference 검증 범위를 확인해주세요. Step 0과 Step 4의 stale +> reference 문구를 PRD/VALIDATION에 맞춘 뒤 `internal-release` Phase를 시작해주세요.