FESADev/docs/nonlinear-static-newton-raphson/implementation-plan.md

# Nonlinear Static Newton-Raphson Implementation Plan

> For Harness workers: this plan is an approved Stage 6 planning artifact. It authorizes planning files only. It does not authorize `scripts/execute.py`, C++ implementation, build, CTest, reference solver execution, or evidence-document creation.

**Goal:** `nonlinear-static-newton-raphson` 기능을 C++17/MSVC/CMake/CTest TDD 순서로 완결하고, current-position/spatial-moment global equilibrium, accepted free residual, fine-primary/coarse-companion reference gate와 HDF5 schema v1을 검증한다.

**Architecture:** App layer가 argv 검증, lexical output path derivation, move-only `OutputWriteLease`, log open/close와 final HDF5 writer 호출 순서를 소유한다. 입력 parse/map은 정확히 한 번 수행하고, `StepDefinition::ProcedureKind()`로 linear와 nonlinear procedure executor를 분리한다. Nonlinear accepted state는 current arm과 spatial physical moment로 applied-plus-reaction balance error를 만들고 기존 `/global/equilibrium`에 저장하며, comparator는 existing schema-v1 nodal datasets에서 constrained reaction resultant와 accepted free residual을 별도로 재구성한다. `LinearStaticAnalysis`의 기존 private lifecycle에는 nonlinear 조건문을 넣지 않는다.

**Tech Stack:** C++17, MSVC on Windows, CMake, CTest, GoogleTest, Intel oneAPI MKL/TBB, HDF5, Abaqus `.inp` approved subset, Python 3 Harness scripts.

**Spec:** `docs/nonlinear-static-newton-raphson/{requirements,research,formulation,numerical-review,reference-model,io}.md`

## Metadata

| key | value |
| --- | --- |
| feature_id | `nonlinear-static-newton-raphson` |
| status | `ready-for-implementation` |
| owner_agent | `implementation-planning-agent` |
| date | `2026-08-28` |
| approval | User approved the original 13-Step draft on `2026-08-24`, USER-DECISION-003 revision, and delegated the Coordinator-audited REAPPROVAL-012 Stage 6 reapproval/materialization with both normalized factor-one global force and moment balance gates fixed at `<=1e-8` on `2026-08-28`. |
| source_requirement | `docs/nonlinear-static-newton-raphson/requirements.md` |
| source_research | `docs/nonlinear-static-newton-raphson/research.md` |
| source_formulation | `docs/nonlinear-static-newton-raphson/formulation.md` |
| source_numerical_review | `docs/nonlinear-static-newton-raphson/numerical-review.md` |
| source_reference_models | `docs/nonlinear-static-newton-raphson/reference-model.md` |
| source_io_definition | `docs/nonlinear-static-newton-raphson/io.md` |

## Approved Upstream Hashes

| document | SHA-256 |
| --- | --- |
| `requirements.md` | `89C1AB5F1BEDB7C5F6AD0726ED62F0982181EA8746EDE4661183FD3D18A2408E` |
| `research.md` raw | `4F63D23E03D1A68E5F8563B678FDD6F761F9558165778EF0433133EFAD303570` |
| `formulation.md` | `878028F7B8EC1B91DA9BF00AF78825F50EB0B71046E840A0EEA595AFFD5E14B9` |
| `numerical-review.md` | `C00994EF4BB23A237547459E157EE5BDA96B28CAF08F712CD31A8E0ABBF62D2C` |
| `reference-model.md` | `B2E6845AB59A32F78261B7A47506C27F7BF4B61401B34BC5DE3DAD4F03D6ADDA` |
| `io.md` raw | `ED23274F4F15F7D1DFF886FA8158961362C75960990271D24A5FD010A8D51FD9` |
| `io.md` LF-normalized | `53AFBB1DF27FBD9CE6C2E23EE34480882241A859D3FC1993E82DB61ACC6637EB` |

## Readiness Check

- Upstream document status: Stage 1 requirements, Stage 4 numerical/reference review and Stage 5 I/O definition are complete; REAPPROVAL-012 fixes both factor-one normalized global force and moment balance gates at `<=1e-8`. Stage 3 formulation §§11.4/13.4 already supplies the accepted residual/reaction/global-resultant meaning.
- Missing decisions: none.
- Missing required comparison files: none. Fine primary, coarse companion and linear-control exact inputs/CSVs are present; stress files are optional inventory only.
- Planning can proceed: yes.
- REWORK-008의 local reaction blocking conflict는 USER-DECISION-004 option 1로 해소되었다. Local nodal RF/RM은 review-only이고 factor-one global force/moment balance와 accepted free residual이 blocking이다. `AUDIT-001` current-arm/spatial-moment implementation seam은 Step 11에서 RED-first로 닫는다.
- Step 11에는 보존해야 할 uncommitted `NSNR-CTRL-018..021`, `NSNR-LOG-012`, `NSNR-PROC-019`,
  `NSNR-HDF5-014`, `NSNR-REF-001..023`, residual-selector GREEN과 comparator/CMake 작업이 있다.
  새 계획은 이를 reset/replay하지 않는다.
- `implementation-report.md`, `build-test.md`, canonical `reference-comparison.md`는 아직 없고 Step 12가 actual evidence에서만 생성한다.
- `CMakePresets.json` tracks the approved `windows-msvc-ninja-debug` contract. The ignored `.harness/config.json` selects the matching configure/build/test presets and `.harness/build-ninja-msvc-debug` binary directory.

## Implementation Scope

Included behavior:

- Existing schema-v1 `/global/equilibrium [6]`에 global origin `[0,0,0]`, accepted current
  position `X+u`, independently spatial-converted applied/reaction moments를 사용하는
  applied-plus-reaction balance error를 기록한다.
- Existing schema-v1 nodal datasets와 exact constraint mask에서 accepted free residual,
  constrained reaction resultant와 global balance error를 서로 다른 evidence로 재구성한다.
- Fine nonlinear primary, coarse nonlinear companion와 linear control을 exact read-only artifact로
  비교한다. U는 blocking, UR은 warning-only, local RF/RM은 review-only, RM3/stress는 excluded다.
- Internal global force/moment는 dimension-separated normalized `1e-8`, accepted free residual은
  NSNR-069으로 blocking 검증하고 external families만 `docs/TOLERANCE.md`를 사용한다.

Excluded behavior and non-goals:

- New HDF5 dataset/schema version, public header/API, tolerance, reference artifact 또는 solver scope
  추가가 아니다.
- `fesa.env`, runtime configuration, CLI option 또는 product solver acceptance behavior를 추가하지
  않는다. `1e-8`은 comparator-owned internal verification gate의 fixed value다.
- Local nodal reaction을 global sum으로 대체하거나 Abaqus S4와 FESA MITC4 내부 정식화
  동등성을 주장하지 않는다.
- Steps 0–10 구현/history replay, selector RED 재현, Abaqus/reference solver 실행, Physics/Release
  판정은 포함하지 않는다.

## Global Constraints

- Use `RED -> observed failure -> minimal GREEN -> focused VERIFY -> full CTest` in every implementation Step.
- C++ production edits require related C++ tests in the same Step.
- Do not edit requirements, research, formulation, numerical review, reference-model, I/O, tolerance, or reference artifacts.
- Do not run Abaqus, Nastran, or any reference solver.
- Do not create `implementation-report.md`, `build-test.md`, or `reference-comparison.md` before Step 12 produces actual command evidence.
- Do not run Harness from this planning approval. `scripts/execute.py` requires a separate explicit request.
- Implementation and Harness execution remain unauthorized by this materialized plan until the user separately requests Executor execution.
- Preserve source label/instance identity, deterministic row order, deterministic diagnostics, finite checks, and `docs/TOLERANCE.md` exactly.
- Residual force/moment channel은 finite-first 검사 뒤 matching external scale 자체로 분기한다. Exact zero이면 denominator output exact `0`과 typed absolute `1.0e-3`; nonzero이면 retained `max(internal,external)` denominator와 dimensionless relative `1.0e-2`만 사용한다. Tolerance band, zero clamp, `max(1,...)`, absolute/relative OR는 금지한다.
- Correction gates, four-channel logical AND, Full Newton, fixed load-factor stepping, maximum 100 iterations와 `nsnr-log-v1` 39-field label/order/TAB schema는 변경하지 않는다.
- Preserve `U1/U2/U3` blocking and `UR1/UR2/UR3` warning-only. Fine/coarse constrained `RF1/RF2`, `RF3`, physical spatial `RM1/RM2` remain review-only with complete deterministic precheck/error reporting; exclude `RM3` and stress from numeric comparison.
- Preserve schema version 1 and all existing HDF5 paths/shapes/components. Do not add a summary dataset or public header.
- Keep internal global balance/free-residual gates separate from external `docs/TOLERANCE.md`; do not add a floor, `max(1,S)`, zero clamp, averaging or collapse.
- Launch every Harness process from VsDevCmd with `-arch=x64 -host_arch=x64` and inherit `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, and `HDF5_DIR`. The tracked preset selects Ninja and MSVC Debug without hard-coding machine-local dependency paths.

## Repository Seam Map

| area | current seam | implementation direction |
| --- | --- | --- |
| CLI/app | `src/fesa/app/fesa_application.cpp` currently accepts `[--output <results.h5>]` and constructs `LinearStaticAnalysis`. | Add output path derivation and `OutputWriteLease`, reject any argv token containing `--output`, own log/HDF5 lifecycle. |
| Analysis request | `include/fesa/analysis/analysis.h` contains `input_path` and `output_path`. | Add `log_path`; Step 10 introduces prepared analysis flow for single parse/map and delayed HDF5 finalization. |
| Linear lifecycle | `LinearStaticAnalysis::Run()` currently parses/maps and writes HDF5 inside `RecoverAndWrite()`. | Refactor into `PrepareAnalysisInput`, `LinearStaticProcedureExecutor`, and final writer call after log close; keep linear numerical behavior. |
| Domain | `StaticStepDefinition` in `include/fesa/model/model_types.h`; `StepDefinition` in `include/fesa/model/domain.h`. | Store procedure identity, `NLGEOM`, raw four `*STATIC` values and provenance. Do not store derived factor sequence or PRESELECT state. |
| Parser mapping | `src/fesa/io/abaqus/domain_mapping_context.cpp`, `step_definition_mapper.cpp`. | Accept nonlinear static subset, warning no-op PRESELECT, reject unsupported procedure fail-closed. |
| MITC4 | `include/fesa/elements/mitc4_shell.h`, `src/fesa/elements/mitc4_shell.cpp` are linear small-rotation. | Add separate nonlinear MITC4 files with `Create(...)` from four nodes, four initial frames, `ShellSection`, and `LinearElasticMaterial`; element kernels compute internal residual/tangent/recovery only. |
| Loads/control | Preserved partial Step 11 work already changes residual selection to matching external scale exact-zero/nonzero and adds `NSNR-CTRL-018..021`/`NSNR-LOG-012`. | Preserve without replay/redesign; run focused regression before the new equilibrium/reference gate. |
| Equilibrium projection | `src/fesa/analysis/nonlinear_static_procedure.cpp` currently sums raw full residual with initial Domain coordinates and raw rotational covectors. | Apply the constraint mask before rotational conversion; use accepted `X+u`; convert applied and constrained-reaction rotational covectors independently with `InverseTransposeLeftJacobianSO3(phi)`; store applied-plus-reaction balance only. |
| Source identity | `SourceEntityId { instance_name, source_label, source_label_text }` and `EntityIndex` exist in `include/fesa/core/source_identity.h`; nodes are stored in stable Domain order. | Step 8 baseline uses both `EntityIndex` and full `SourceEntityId`, requires one node baseline per Domain node in stable internal order, rejects label-only or mismatched identities, and preserves identity into HDF5/reference mapping. |
| Solver | `MklPardisoSolver` uses SPD `mtype=2` and upper-triangle copy. | Preserve unchanged; add `TangentSolver` and MKL unsymmetric full CSR `mtype=11`. |
| Results writer | `NonlinearHdf5ResultsWriter` already writes schema-v1 `/global/equilibrium`, but its location attribute is `global-origin`. | Preserve dataset path/shape/components and change exact location identity to `global-balance-error`; no new dataset or public writer boundary. |
| Tests | Existing integration/HDF5 tests and partial nonlinear comparator are registered in existing executables. | Add RED to existing sources; preserve the current CMake registration and use focused `ctest -R` regex without a new target or global relabel. |

## Work Breakdown

| Step | name | dependency | primary responsibility |
| ---: | --- | --- | --- |
| 0 | `cli-output-lease-and-derived-names` | none | CLI output derivation, `--output` substring rejection, RAII output lease, app-owned log/HDF5 lifecycle entry. |
| 1 | `nonlinear-static-domain-contract` | 0 | Domain/parser semantic contract for `NLGEOM=YES`, raw `*STATIC`, PRESELECT warning no-op. |
| 2 | `finite-rotation-state` | 1 | SO(3) finite rotation state, left Jacobian, branch/invariant validation. |
| 3 | `nonlinear-mitc4-kinematics-and-recovery` | 1,2 | TL MITC4 nonlinear kinematics and recovery rows. |
| 4 | `nonlinear-mitc4-residual-and-tangent` | 2,3 | Same-trial internal residual and internal consistent tangent with recovery. |
| 5 | `load-boundary-path-and-convergence-gates` | 1-4 | Fixed factor path, proportional load/BC path, global-once fixed-load `f_ext`/`K_ext` with approved subtraction signs, `rho_M`, typed four-channel convergence with constants owned by evaluator. |
| 6 | `backend-neutral-tangent-solver` | 4 | Separate nonsymmetric tangent solver boundary and MKL adapter. |
| 7 | `newton-iteration-log-writer` | 0,5 | Exact 39-field Newton text log writer. |
| 8 | `nonlinear-state-commit-rollback` | 3-7 | Factor-zero baseline construction with `EntityIndex` plus `SourceEntityId`, trial/committed nonlinear state, accepted frames, rollback/preservation. |
| 9 | `nonlinear-hdf5-schema-v1-writer` | 8 | Nonlinear HDF5 schema v1 writer using `std::vector<Diagnostic>`. |
| 10 | `prepared-analysis-flow-and-full-procedure` | 0-9 | Single parse/map prepared analysis flow, separate linear/nonlinear executors, delayed writer finalization. |
| 11 | `equilibrium-projection-and-reference-gate` | 0-10 | Preserve partial selector/comparator work; add new current-arm/spatial-moment, HDF5 location, fine/coarse disposition/internal-gate RED tests; make minimal procedure/writer/comparator GREEN; run focused/full verification. |
| 12 | `execution-closure-and-evidence-docs` | 0-11 | Fresh MSVC evidence, deterministic repeat/reference audit, actual-output evidence docs. |

## TDD Test Plan

| test id family | RED assertion scope | Step |
| --- | --- | --- |
| `NSNR-CLI-*` | `--output` substring first-token rejection, lexical result/log names, no-output-change proof, lease lifetime. | 0 |
| `NSNR-IO-*` | `NLGEOM=YES`, raw `*STATIC`, `NLGEOM=NO` regression, PRESELECT warning no-op, unsupported procedure diagnostics. | 1 |
| `NSNR-ROT-*` | finite rotation invariants, `J_l`, branch margin, director update. | 2 |
| `NSNR-ELEM-KIN-*` | nonlinear MITC4 creation inputs, TL shell kinematics, fixed-size four-GP recovery rows, degeneracy fail-closed, linear limit. | 3 |
| `NSNR-ELEM-TAN-*` | same-trial internal residual/tangent, directional derivative, objectivity, symmetry only for internal/no-external cases. | 4 |
| `NSNR-CTRL-*` | Existing coverage plus preserved partial `NSNR-CTRL-018..021`: matching-external exact-zero absolute boundaries, retained nonzero relative boundaries, nonfinite-first/no-clamp selection, unchanged correction gates/four-channel AND. Do not replay/fabricate selector RED. | 5,11 |
| `NSNR-SOLVER-*` | nonsymmetric tangent solve, 0x0, nonfinite/failure translation, SPD solver unchanged. | 6 |
| `NSNR-LOG-*` | Existing serializer coverage plus preserved partial `NSNR-LOG-012`: evaluator-produced zero/nonzero-external decisions retain exact denominator, branch, threshold, unit and 39 fields. | 7,11 |
| `NSNR-STATE-*` | factor-zero baseline creation with stable node order and full source identity, trial/committed separation, accepted frame order, full schema-v1 state inventory, finite atomic commit, rollback. | 8 |
| `NSNR-HDF5-*` | Existing schema-v1 coverage plus `NSNR-HDF5-014` exact `/global/equilibrium` `location=global-balance-error`; path/shape/components/version unchanged. | 9,11 |
| `NSNR-PROC-*` | Existing procedure coverage plus collision-resolved `NSNR-PROC-019` exact test `NonlinearStaticProcedure.NonzeroPrescribedMotionWritesCurrentArmSpatialAppliedPlusReactionBalance`. Approved draft label `NSNR-PROC-011` is not reused because completed Step 10 already owns it. | 10,11 |
| `NSNR-REF-*` | Preserve `NSNR-REF-001..023`, including the current-case old-gate RED in `022`; add `024` inclusive `1e-8` force/moment boundary plus approved between-threshold regression and `025` exact-zero-scale force/moment regression before changing the comparator gate. | 11 |
| `NSNR-EVID-*` | `001..007` freshness, disposition, fine/internal inventory, AUDIT-001, command/provenance and actual-output report checks. | 12 |

## CMake And CTest Plan

- Add C++ sources to `src/fesa/CMakeLists.txt` under existing `fesa_solver`.
- Add unit tests to `fesa_unit_tests`, integration tests to `fesa_integration_tests`, reference tests to `fesa_reference_tests`.
- Preserve current executable-wide labels. Use focused regex such as `ctest --preset windows-msvc-ninja-debug -R "NonlinearStaticReference|ReferenceTolerance|Mitc4Reference" --output-on-failure`.
- Step 11 adds no target or `add_test`: procedure/HDF5 tests use existing executables and current partial `tests/CMakeLists.txt` comparator registration is preserved without unrelated edits.
- If scoped per-test labels are introduced, the Step that introduces the mechanism must test it and avoid changing labels for unrelated discovered tests.
- Configure/build/test commands:

```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 --output-on-failure
```

## Candidate Files and Ownership

Candidate paths guide the Implementation Agent and do not finalize a new public API.

| Step | candidate files | responsibility boundary |
| --- | --- | --- |
| 11 RED | `tests/integration/analysis/nonlinear_static_procedure_test.cpp`; `tests/unit/io/hdf5/nonlinear_hdf5_results_writer_test.cpp`; existing partial `tests/reference/nonlinear_static_reference_{comparison.h,comparison.cpp,cases_test.cpp}` | New behavior must fail before production edits; comparator extensions remain test-private. |
| 11 GREEN | `src/fesa/analysis/nonlinear_static_procedure.cpp`; `src/fesa/io/hdf5/nonlinear_hdf5_results_writer.cpp` | Current-arm/spatial-moment balance and exact dataset location only; no public header/state/schema expansion. |
| 11 preserve | `src/fesa/analysis/nonlinear_static_control.cpp`; `tests/unit/analysis/nonlinear_static_control_test.cpp`; `tests/unit/analysis/newton_iteration_log_test.cpp`; `tests/CMakeLists.txt` | Preserve uncommitted selector/tests/registration and verify them; do not reset, recreate or redesign. |
| 12 evidence | `docs/PRD.md`; `docs/ARCHITECTURE.md`; `docs/ADR.md`; feature `implementation-report.md`, `build-test.md`, `reference-comparison.md` | Directly superseded global statements and actual evidence only; no C++/test/CMake ownership. |

## Data Flow Contract

1. CLI receives `fesa.exe <model.inp>`.
2. App scans all argv tokens left-to-right. The first token containing case-sensitive substring `--output` fails with one `cli-usage` diagnostic before path resolution, parse/map, analysis, lease, log, or HDF5.
3. App derives `<stem>_results.h5` and `<stem>_log.txt` beside the lexically normalized user-addressed `.inp`.
4. App acquires move-only `OutputWriteLease` and retains it until all log and HDF5 work ends.
5. App opens/truncates the log, then `PrepareAnalysisInput(input_path)` parses/maps once into `Domain`.
6. Procedure executor receives injected `ParallelFor` plus `LinearSolver` or `TangentSolver` and computes a fully validated state without opening HDF5. Nonlinear assembly forms `r=f_int-f_ext` and `K_T=K_int-K_ext`, preserves the existing convergence decisions, then computes accepted global balance in stable node order. For each node it sets `x=X+u`, masks constrained residual components before converting reaction rotation, converts applied and reaction rotational covectors independently with `InverseTransposeLeftJacobianSO3(phi)`, and accumulates `applied+reaction` force and `x cross force + spatial moment` about `[0,0,0]`.
7. App closes the log successfully before invoking injected `ResultsWriter` or `NonlinearResultsWriter`.
8. HDF5 is authoritative. Existing schema-v1 `/global/equilibrium [6]` stores only the applied-plus-reaction balance error with `location=global-balance-error`; existing nodal datasets/mask reconstruct accepted free residual and constrained reaction resultant without new datasets.
9. Comparator copies exact inputs to unique build-local directories, runs only the copies, and executes `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`. CSV views are comparison/debug artifacts only.

## Reference Inventory

| path | role | rows | SHA-256 |
| --- | --- | ---: | --- |
| `reference/shellNL-meshfine/shellNL-meshfine.inp` | primary nonlinear input | input | `40DF1CE77311C8D799564A21A60F3BDEBB8148D52CAE22B7292FDFAD32018220` |
| `reference/shellNL-meshfine/shellNL-meshfine displacements.csv` | required blocking/warning CSV | 729 | `740819FF8AED0E279961581F7CDBFA12784CFBA3A488C35A652E80103F64433F` |
| `reference/shellNL-meshfine/shellNL-meshfine reactions.csv` | required review-only CSV | 729 | `AEB01C98C596792B0E5F2B86A81945CAB0BEB0C6969CFC6738C6F81DF1F94363` |
| `reference/shellNL-meshfine/shellNL-meshfine stresses.csv` | optional inventory artifact | 5,408 | `6D6213AB5DB9D6B1F5FBD641367D08BACC805967B6C5A95BCE0E1A5395377782` |
| `reference/shellNL/shellNL.inp` | nonlinear input | input | `4BF3ECB0F7F1E8462C573E993DBC97AC5D920C91CF6F23AD4C6891D77FFBADA2` |
| `reference/shellNL/shellNL displacements.csv` | required blocking/warning CSV | 49 | `4E0F99CA9372B1ADF7FAF102F43BC0B887DC743FDEDA378E4342D2CF8E0C0786` |
| `reference/shellNL/shellNL reactions.csv` | required review-only CSV | 49 | `001CB1541A9E94424E5E650509D46BC8724970DF4DE47184D9DB09C7938AB069` |
| `reference/shellNL/shellNL stresses.csv` | optional inventory artifact | 288 | `5500E5114B1C44887528E30CEC054A1EB0F68BE3F4B8CE81FA59FC74A881483F` |
| `reference/shell/shell.inp` | linear input | input | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` |
| `reference/shell/shell displacements.csv` | required displacement CSV | 49 | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` |
| `reference/shell/shell reactions.csv` | nonblocking inventory artifact | 49 | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` |
| `reference/shell/shell stresses.csv` | nonblocking inventory artifact | 288 | `2B75A5B0DEB045A283C9BB7E9B1153B79F7537FF487214BF4A23316B59B660A7` |

External comparison families:

| family | components | rows | disposition |
| --- | --- | ---: | --- |
| `linear.translation` | `U1,U2,U3`, nodes `1..49` | 147 | blocking |
| `linear.rotation` | `UR1,UR2,UR3`, nodes `1..49` | 147 | warning-only |
| `coarse.translation` | `U1,U2,U3`, nodes `1..49` | 147 | blocking |
| `coarse.rotation` | `UR1,UR2,UR3`, nodes `1..49` | 147 | warning-only |
| `coarse.local_reaction_inplane_force` | `RF1,RF2`, 24 constrained nodes | 48 | review-only |
| `coarse.local_reaction_transverse_force` | `RF3`, 24 constrained nodes | 24 | review-only |
| `coarse.local_reaction_physical_moment` | `RM1,RM2`, 24 constrained nodes | 48 | review-only |
| `fine.translation` | `U1,U2,U3`, nodes `1..729` | 2,187 | blocking |
| `fine.rotation` | `UR1,UR2,UR3`, nodes `1..729` | 2,187 | warning-only |
| `fine.local_reaction_inplane_force` | `RF1,RF2`, 104 constrained nodes | 208 | review-only |
| `fine.local_reaction_transverse_force` | `RF3`, 104 constrained nodes | 104 | review-only |
| `fine.local_reaction_physical_moment` | `RM1,RM2`, 104 constrained nodes | 208 | review-only |

Internal blocking families for each fine/coarse accepted factor-one state are free force residual,
free moment residual, global force balance and global moment balance. Global force/moment use separate
normalized `<=1e-8` gates; free residual uses NSNR-069. Constrained reaction resultant force `[3]`
and moment `[3]` is a distinct review-only summary.

Constrained labels: coarse `1,3..9,14..17,22..33`; fine `1,3..9,34..57,82..153`.

Exact fine and coarse nonlinear `Frame`: `Increment     10: Step Time =    1.000`.

Step 11 must not run original reference input paths directly. It snapshots each exact original artifact inventory, copies input bytes unchanged into a unique build-local case directory, runs `FesaApplication` on the copy, consumes copied-sibling `_results.h5` and `_log.txt`, compares generated HDF5 to original read-only CSVs, and verifies original inventory, bytes, timestamps and hashes are unchanged. HDF5 path identity matches the copied input and source content identity matches the approved input hash.

## Acceptance Traceability Matrix

| requirement | Steps | test ids |
| --- | --- | --- |
| `FESA-REQ-NSNR-001` | 1,10 | `NSNR-IO-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-003` | 1,3,4,10 | `NSNR-IO-*`, `NSNR-ELEM-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-041` | 1,3,10 | `NSNR-IO-*`, `NSNR-ELEM-KIN-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-074` | 2,8,10 | `NSNR-ROT-*`, `NSNR-STATE-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-006` | 4,6,10 | `NSNR-ELEM-TAN-*`, `NSNR-SOLVER-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-007` | 5,10,11 | `NSNR-CTRL-021`, `NSNR-PROC-*`, `NSNR-REF-019` |
| `FESA-REQ-NSNR-069` | 5,10,11 | `NSNR-CTRL-018..020`, `NSNR-LOG-012`, `NSNR-REF-019` |
| `FESA-REQ-NSNR-070` | 5,10,11 | `NSNR-CTRL-021`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-008` | 5,10,11 | `NSNR-CTRL-020`, `NSNR-PROC-*`, `NSNR-REF-019` |
| `FESA-REQ-NSNR-014` | 5,10 | `NSNR-CTRL-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-046` | 5,10 | `NSNR-CTRL-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-048` | 5,10 | `NSNR-CTRL-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-018` | 5,10 | `NSNR-CTRL-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-063` | 5,10 | `NSNR-CTRL-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-016` | 1,5 | `NSNR-IO-*`, `NSNR-CTRL-*` |
| `FESA-REQ-NSNR-011` | 8,9,10 | `NSNR-STATE-*`, `NSNR-HDF5-*`, `NSNR-PROC-*` |
| `FESA-REQ-NSNR-019` | 4,8,10,11 | `NSNR-ELEM-TAN-*`, `NSNR-STATE-*`, `NSNR-PROC-019`, `NSNR-HDF5-014`, `NSNR-REF-022`, `NSNR-REF-024..025` |
| `FESA-REQ-NSNR-020` | 1 | `NSNR-IO-*` |
| `FESA-REQ-NSNR-021` | 8,9,10,11 | `NSNR-STATE-*`, `NSNR-HDF5-*`, `NSNR-PROC-*`, `NSNR-HDF5-014` |
| `FESA-REQ-NSNR-024` | 7,10,11 | `NSNR-LOG-012`, `NSNR-PROC-*`, `NSNR-REF-019` |
| `FESA-REQ-NSNR-083` | 0,10,12 | `NSNR-CLI-*`, `NSNR-PROC-*`, `NSNR-EVID-*` |
| `FESA-REQ-NSNR-026` | 8,10,11,12 | `NSNR-STATE-*`, `NSNR-PROC-*`, `NSNR-REF-020..023`, `NSNR-EVID-*` |
| `FESA-REQ-NSNR-030` | 2,3,4,5,6,7,8,9,10,11 | `NSNR-ROT-*`, `NSNR-ELEM-*`, `NSNR-CTRL-*`, `NSNR-SOLVER-*`, `NSNR-LOG-*`, `NSNR-STATE-*`, `NSNR-HDF5-014`, `NSNR-PROC-019`, `NSNR-REF-022`, `NSNR-REF-024..025` |
| `FESA-REQ-NSNR-034` | 11,12 | `NSNR-REF-020..023`, `NSNR-EVID-003..007` |

## Numerical Review Coverage

| category | Steps |
| --- | --- |
| linear-limit reduction | 3,4,10,11 |
| rotation invariants and branch margin | 2,8,10 |
| tangent directional derivative schedule | 4 |
| no-moment tangent symmetry | 4 |
| finite rigid objectivity | 3,4 |
| patch/sign recovery | 3,4 |
| load/boundary path and `rho_M` | 5,10 |
| Newton factor/iteration lifecycle | 5,7,10 |
| four convergence gates | 5,7,10,11; preserved partial selector/control/log work is regression-verified in Step 11 |
| global balance/current-arm/spatial moment | 11 |
| review-only local reaction and fine/coarse reference | 11,12 |
| commit/rollback/determinism | 8,10,11,12 |

## Validation Commands

Each Step must:

1. Use the ignored `.harness/config.json` preset contract and tracked `CMakePresets.json`.
2. Confirm the Harness parent environment was initialized by VsDevCmd x64 and contains `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, and `HDF5_DIR`.
3. Run:

```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 --output-on-failure
```

Step 11 focused commands additionally include:

```powershell
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 -R "^NonlinearStaticReference\." --output-on-failure
ctest --preset windows-msvc-ninja-debug -R "^(NonlinearStaticReference|ReferenceTolerance|Mitc4Reference)\." --output-on-failure
```

Harness Python validation is not in scope unless a Step changes Harness Python behavior, hook behavior, or agent configuration.

## Risks And Downstream Handoff

- Current numerical risk: nonzero prescribed motion exposes the existing raw-residual/initial-arm
  shortcut. The minimal fix must preserve same-state, stable-order and mask-before-spatial-conversion
  semantics; passing zero-prescribed shellNL cases alone is insufficient evidence.
- Current reference risk: fine/coarse U and internal balance/free-residual are blocking, but local RF/RM
  may still show large review-only errors. Do not convert those findings into omitted rows, relaxed
  tolerance or a blocking gate.
- Current worktree risk: Step 11 contains partial selector/comparator/CMake edits. Preserve and continue
  those files; do not delete, reset, replay selector RED or replace the comparator design wholesale.
- Handoff to Implementation Agent through Coordinator: after a separate explicit Harness request,
  resume only Executor-selected Step 11. Preserve existing `NSNR-PROC-019`, `NSNR-HDF5-014` and
  `NSNR-REF-020..023`; first re-observe the current-case old-gate RED, then add `NSNR-REF-024..025`
  before changing the comparator-only shared force/moment gate to `1e-8`. Verify preserved
  selector/log tests, then run focused/full preset validation.
  Step 12 remains actual-evidence closure.

## Harness Step Draft

| Step | name | one-module scope | prerequisites | stop condition |
| ---: | --- | --- | --- | --- |
| 11 | `equilibrium-projection-and-reference-gate` | Nonlinear accepted equilibrium projection, exact HDF5 location and test-private reference gate | Steps 0–10 completed; approved upstream hashes; partial Step 11 work preserved; VsDevCmd/preset dependency environment | Stop on unexpected RED, public API/schema/tolerance/reference change, reference mutation, or any focused/full failure. |
| 12 | `execution-closure-and-evidence-docs` | Fresh evidence reports plus directly superseded PRD/ARCH/ADR statements | Step 11 completed with actual command/reference evidence | Stop if Step 11 is incomplete, evidence is stale/untraceable, a code/test/CMake change is needed, or any final command fails. |

Both Step files contain exact commands, file ownership, RED/GREEN/VERIFY order and prohibitions.
Materialization does not select or execute either Step.

## Open Issues

None blocking planning. Revised upstream contracts and exact required artifacts are complete; actual
RED/GREEN/build/reference outcomes remain Step 11/12 evidence and are not pre-claimed.

## Plan Approval Boundary

The Coordinator-audited REAPPROVAL-012 revision authorizes this planning/phase materialization and
blocked-to-pending recovery. It does not itself execute Harness; Executor invocation remains under
the Coordinator's separately audited execution authority.