docs: add linear static beam harness phase

2026-08-09 01:35:44 +09:00
parent 3410828736
commit 6d6da7545c
36 changed files with 3524 additions and 54 deletions
@@ -0,0 +1,91 @@
+# Step 27: Physics Sanity
+
+## 담당 역할과 필수 스킬
+
+- 담당 역할: `physics-evaluation-agent`
+- 필수 스킬: `fesa-physics-sanity`
+- reference tolerance를 다시 판정하지 말고 documented physical expectation만 평가하라.
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/physics-evaluations/README.md`
+- `/docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md`
+- `/docs/reference-models/linear-static-3d-euler-beam-reference-models.md`
+- `/docs/requirements/linear-static-3d-euler-beam.md`
+- `/docs/formulations/3d-isoparametric-euler-beam-formulation.md`
+- `/docs/numerical-reviews/linear-static-3d-euler-beam-review.md`
+- `/docs/io-definitions/linear-static-3d-euler-beam-io.md`
+- `/.harness/build/reference/cantilever-beam-b33/results.h5`
+- `/.harness/build/reference/cantilever-beam-b33/comparison.json`
+- `/reference/cantilever beam/`의 승인된 read-only artifact
+
+## 작업
+
+Reference Verification status가 `pass-for-physics-evaluation`인지 먼저 확인하고
+`docs/physics-evaluations/linear-static-3d-euler-beam-physics-evaluation.md`를 생성하라.
+
+다음 physical check를 documented expectation과 observed HDF5/comparison evidence로 각각
+판정한다.
+
+- global applied force + reaction force equilibrium
+- origin 기준 applied/reaction force moment와 reaction moment equilibrium
+- constrained DOF reaction consistency와 free residual normalized `1e-10`
+- load 방향에 대한 displacement/rotation direction과 sign
+- expected zero/symmetry components
+- adjacent element endpoint section resultant consistency와 boundary end action balance
+- local/global component mapping, section-force signs, `S11` location/sign sanity
+- nonfinite, rigid-body-mode, 비정상 magnitude/energy 징후
+- B33 cantilever가 검증하는 범위와 line-load/rotated/analytical unit test가 보완하는 coverage
+
+각 check에 식, unit, coordinate system, observed value/norm, criterion, verdict를 기록한다.
+Stress는 Abaqus reference comparison 없이 schema/unit/analytical evidence로만 sanity를
+평가한다고 명시한다. 모든 documented check가 통과하면 Metadata와 Evaluation Verdict를
+`pass-for-release-agent`로 둔다. No-Change Assertion을 포함한다.
+
+## Acceptance Criteria
+
+```powershell
+$referenceReport = 'docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md'
+if (-not (Select-String -LiteralPath $referenceReport `
+    -SimpleMatch 'status: `pass-for-physics-evaluation`' -Quiet)) {
+  throw 'Reference verification gate is not passing'
+}
+ctest --test-dir .harness/build -C Debug -R "EulerBeam3D|ResultRecovery|B33ReferenceComparison" --output-on-failure
+if (-not (Test-Path '.harness/build/reference/cantilever-beam-b33/results.h5')) { throw 'Missing solver HDF5 evidence' }
+if (-not (Test-Path '.harness/build/reference/cantilever-beam-b33/comparison.json')) { throw 'Missing normalized comparison/physics evidence' }
+git diff --exit-code -- reference/
+```
+
+```powershell
+$path = 'docs/physics-evaluations/linear-static-3d-euler-beam-physics-evaluation.md'
+if (-not (Test-Path $path)) { throw "Missing $path" }
+$required = @('status: `pass-for-release-agent`', '## Input Evidence', '## Physics Checks',
+  'global equilibrium', 'reaction consistency', 'displacement direction',
+  'element force', 'stress', '## No-Change Assertion')
+foreach ($text in $required) {
+  if (-not (Select-String -LiteralPath $path -SimpleMatch $text -Quiet)) {
+    throw "Missing physics evidence: $text"
+  }
+}
+git diff --check -- $path
+```
+
+## 검증 절차
+
+1. Passing reference report와 exact solver artifact identity를 확인한다.
+2. 각 physical expectation을 HDF5/metrics/test evidence로 계산·검토한다.
+3. 모두 통과한 경우에만 report와 Step 27을 pass/completed로 갱신한다.
+4. 실패는 physics classification과 owning agent handoff를 기록하고 Step 27을 `error`로 둔다.
+   추가 reference model/사용자 결정이 필수이면 `blocked`로 둔다.
+
+## 금지사항
+
+- source, tests, CMake, upstream reports/contracts를 수정하지 마라. 이유: independent physics gate다.
+- reference tolerance 성공을 다시 판정하거나 완화하지 마라. 이유: Step 26 책임이다.
+- undocumented expectation으로 pass를 만들지 마라. 이유: 검토 traceability가 사라진다.
+- Abaqus 실행 또는 reference artifact 변경을 하지 마라. 이유: read-only evidence다.
+- release readiness를 승인하지 마라. 이유: Step 28 책임이다.
+- 직접 commit하지 마라. 이유: Harness executor가 담당한다.