FESADev/phases/nonlinear-static-newton-raphson/step12.md

# Step 12: execution-closure-and-evidence-docs

> 과거 개발 계획이다. 아래 작업·상태·예시는 현재 실행 지시가 아니다.
> 현재 구현과 검증 한계는 [기능 요약](../../docs/nonlinear-static-newton-raphson/README.md)을 따른다.

## 목적

Step 11이 실제로 통과한 뒤에만 fresh MSVC/CTest와 reference gate evidence를 수집하고 Stage 6
canonical reports를 actual output으로 작성한다. 직접 superseded된 PRD/ARCHITECTURE/ADR 문장만
최소 동기화한다. 이 Step은 solver 동작을 새로 구현하지 않는다.

## 읽어야 할 파일

- `AGENTS.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/nonlinear-static-newton-raphson/README.md`
- `../../docs/nonlinear-static-newton-raphson/formulation.md` §§11.4, 13.1, 13.4, 14.1
- `../../docs/nonlinear-static-newton-raphson/README.md` §§3.2, 6.2, 6.3
- `../../docs/nonlinear-static-newton-raphson/README.md` §§3–6
- `../../docs/nonlinear-static-newton-raphson/README.md` §§7.5.1, 8.1–8.7
- `../../docs/nonlinear-static-newton-raphson/README.md`
- `../../docs/nonlinear-static-newton-raphson/README.md` §13
- `phases/nonlinear-static-newton-raphson/index.json`
- `phases/nonlinear-static-newton-raphson/step11.md`
- All source/test/CMake files actually changed by Steps 0–11
- 과거 검증 자료(정리됨)
- `CMakePresets.json`

## 시작 전 hard gate

- Steps 0–10의 completed history를 그대로 유지한다.
- Step 11 must be `completed` with an actual summary and passing RED/GREEN/VERIFY evidence.
- If Step 11 is not completed, stop without creating/updating evidence docs or global docs.
- Do not infer Step 11 success from a prior blocked run, diagnostic spike or translation-only report.

## 소유 파일

- Modify only directly superseded statements: `../../docs/solver-core/README.md`
- Modify only directly superseded statements: `../../docs/solver-core/README.md`
- Modify only directly superseded decisions or add the minimum accepted decision record:
  `../../docs/solver-core/README.md`
- Create from actual outputs: `../../docs/nonlinear-static-newton-raphson/README.md`
- Create from actual outputs: `../../docs/nonlinear-static-newton-raphson/README.md`
- Create from actual outputs: `../../docs/nonlinear-static-newton-raphson/README.md`

No C++ production, public header, test, CMake, Harness, reference or tolerance file is owned by this
Step.

## RED: evidence freshness audit

Perform this audit before writing reports. The expected initial result is failure because the three
canonical reports are missing or do not contain this Step's fresh evidence.

- `NSNR-EVID-001`: `implementation-report.md` is missing or stale unless it records every Step 11 new
  RED test, the observed reason, minimal GREEN diff, focused/full VERIFY and preserved
  `NSNR-CTRL-018..021`/`NSNR-LOG-012` evidence.
- `NSNR-EVID-002`: `build-test.md` is missing or stale unless it records fresh configure, build,
  discovery, focused/full CTest commands with exit code, duration, output tail, MSVC x64 Debug
  environment, warning audit and failure classification.
- `NSNR-EVID-003`: `reference-comparison.md` is missing or stale unless it records the literal
  `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` run with exact paths/hashes, generated HDF5/log
  paths, projection, row decisions, metrics, classification and no-change evidence.
- `NSNR-EVID-004`: evidence or global docs are stale if they still classify local RF/RM as blocking,
  omit review-only findings, identify coarse shellNL as the only nonlinear case, or describe
  `/global/equilibrium` as raw full-residual/initial-arm evidence.
- `NSNR-EVID-005`: reference evidence is stale if it lacks fine-primary/coarse-companion/linear-control
  inventory, separate U/UR/local reaction families, four coarse and four fine internal blocking
  equilibrium families, the inclusive `1e-8` force/moment boundary and exact-zero-scale regressions,
  and the distinct constrained-reaction summary.
- `NSNR-EVID-006`: implementation evidence is stale unless it closes `AUDIT-001` with actual tests for
  nonzero prescribed translation/rotation, `x=X+u`, mask-before-conversion, independent
  `InverseTransposeLeftJacobianSO3(phi)` conversion, and `location=global-balance-error`.
- `NSNR-EVID-007`: command evidence is stale if copied from an earlier run, omits artifact pre/post
  immutability, lacks command output/exit/duration, changes the required stage order, or claims a
  verdict before CLASSIFY.

Record this expected failing freshness audit in `implementation-report.md` only after fresh evidence
has been collected. If the audit unexpectedly passes before this Step's commands, stop and report the
evidence provenance conflict.

## GREEN: fresh evidence execution

Use the ignored 과거 검증 자료(정리됨) and tracked `windows-msvc-ninja-debug` preset. The parent
environment must be VsDevCmd x64 and contain `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, and
`HDF5_DIR`.

### 1. Fresh build and regression evidence

```powershell
cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug --show-only=json-v1
ctest --preset windows-msvc-ninja-debug -R "^(NonlinearConvergence|NewtonIterationLog)\." --output-on-failure
ctest --preset windows-msvc-ninja-debug -R "^(NonlinearStaticProcedure|NonlinearHdf5ResultsWriter)\." --output-on-failure
ctest --preset windows-msvc-ninja-debug --output-on-failure
```

Record command, working directory, exit code, duration, stdout/stderr tail and failed-test inventory.
Audit new compiler warnings. Stop at the first decisive failure and classify it as
`configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`.

### 2. Final reference gate in literal order

#### ARTIFACT CHECK

- Verify every exact fine/coarse/linear input/CSV path and SHA-256 from `reference-model.md` and
  `step11.md`.
- Verify readable headers, exact nonlinear factor-one Frame, source node/component inventories,
  uniqueness and finite required values.
- Snapshot original inventory, size, timestamps and hashes before any copied-input run.
- Verify generated results will be written only under unique build-local copied-input directories.

#### COMPARE

```powershell
ctest --preset windows-msvc-ninja-debug -R "^NonlinearStaticReference\." --output-on-failure
ctest --preset windows-msvc-ninja-debug -R "^(NonlinearStaticReference|ReferenceTolerance|Mitc4Reference)\." --output-on-failure
```

Compare by `(case_id, accepted_state, canonical_instance_name, source_node_label, component)`, never
by row order. Apply `../../docs/solver-core/README.md` only to external U/UR/local-review families. Apply internal
`1e-8` force/moment balance and NSNR-069 free-residual gates separately. Preserve the exact
blocking/warning/review/excluded dispositions.

#### CLASSIFY

- Blocking pass requires fine/coarse U families, linear U regression and all eight fine/coarse
  internal equilibrium families to pass.
- UR failure is warning-only.
- Local RF/RM precheck/row/RMS failure is a deterministic review finding and cannot change blocking
  pass/fail.
- RM3/stress values are excluded.
- Any blocking missing/extra/duplicate/nonfinite row fails before tolerance.
- Classify actual failures without relaxing tolerance, changing artifacts or claiming external solver
  internal equivalence.

#### REPORT

Only after CLASSIFY, write the three canonical reports from actual outputs.

## Report contracts

### `implementation-report.md`

Record metadata, approved upstream hashes, Steps 0–10 preserved summaries, Step 11 RED failures,
minimal GREEN file/symbol changes, focused/full VERIFY commands and results, `AUDIT-001` closure,
requirement/test traceability, no-change assertion, classification and open issues. Do not invent
unobserved output.

### `build-test.md`

Use `owner_agent: implementation-agent`. Record execution environment, exact commands, working
directories, exit codes, durations, output tails, discovered test inventory, focused/full results,
new-warning audit, failure classification, failed tests, handoff recommendation, no-change assertion
and open issues.

### `reference-comparison.md`

Record exact input/CSV SHA inventory, copied input and generated HDF5/log paths, accepted factor-one
frame, every HDF5 projection/path/component, stable source-key matching, row prechecks, external
common tolerance, internal gates, per-family/per-row decisions, max absolute error, applicable
relative error, RMS/scale metric, constrained-reaction summary, warnings/review findings, final
classification, original artifact post-run identity, no-change assertion and open issues.

The report must explicitly state that FESA HDF5 is authoritative, CSV is external comparison
evidence, and numerical agreement does not imply Abaqus S4 internal formulation equivalence.

## Minimal PRD/ARCHITECTURE/ADR sync

After actual passing evidence exists, update only statements directly superseded by the implemented
feature:

- repository-wide derived result/log names and removal of `--output`;
- prepared parse-once linear/nonlinear procedure boundary and separate nonlinear state/solver/writer;
- nonlinear HDF5 schema v1 accepted-frame meaning;
- `/global/equilibrium` as current-arm/spatial-moment applied-plus-reaction balance error;
- distinct accepted free residual and constrained reaction resultant projections;
- fine primary/coarse companion, U blocking, UR warning-only, local RF/RM review-only and RM3/stress
  exclusion.

Do not rewrite unrelated V0 history, refactor architecture prose or add future scope.

## Final validation

```powershell
git diff --check
git status --short
```

Confirm the original reference pre/post hashes, sizes, timestamps and inventory are equal. Confirm
that every required report statement is backed by a command or deterministic artifact observation.
Harness Python validation is not required because this Step does not change Harness Python, hooks or
agent configuration.

## Acceptance Criteria

- Evidence freshness audit initially fails for the declared stale/missing reason and is recorded.
- Fresh configure/build/discovery/focused/full CTest all pass with MSVC x64 Debug and no new warnings.
- Final gate executes in exact order `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`.
- All blocking external and internal families pass; warnings and review findings remain
  nonblocking and are fully reported.
- `AUDIT-001`, fine/coarse roles and reaction disposition have direct test/output evidence.
- Three canonical Stage 6 reports contain reproducible commands, metrics, classifications and
  no-change assertions.
- PRD/ARCHITECTURE/ADR edits are limited to directly superseded statements.
- `git diff --check` passes and reference artifacts remain byte-for-byte unchanged.

## 상태 기록

On success, update only Step 12 to `completed` and add one concise `summary`. Executor owns
timestamps, commits, top-level completion and advancement. A passing Step 12 returns Stage 6 evidence
to Coordinator; it does not itself dispatch Physics or Release.

## 금지사항

- Do not create or update evidence reports before actual fresh output exists. 이유: Stage 6 reports
  are execution evidence, not predictions.
- Do not change C++ code, tests, CMake, Harness configuration, tolerance or reference artifacts.
  이유: Step 12 is evidence closure only.
- Do not reorder or collapse `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`. 이유: schema and
  identity failures must precede tolerance and verdict.
- Do not make local RF/RM blocking, omit their errors, or compare RM3/stress. 이유:
  USER-DECISION-004 fixes the disposition.
- Do not use Abaqus CSV/tolerance for internal balance/free-residual gates or claim Abaqus internal
  equivalence. 이유: external comparison and internal physics evidence are distinct.
- Do not broadly rewrite PRD/ARCHITECTURE/ADR, alter Steps 0–11 history, commit, push, run a reference
  solver, or claim Physics/Release readiness.