FESADev/docs/nonlinear-static-newton-raphson/requirements.md

# Nonlinear Static Newton–Raphson 요구조건

## 1. Metadata
- feature_id: `nonlinear-static-newton-raphson`
- title: `Nonlinear Static Analysis Using Newton–Raphson`
- status: `draft`
- owner_agent: `requirement-agent`
- date: `2026-08-27`
- approved_by: pending user re-approval
- approval_date: pending
- authoritative_scope: materially linear, geometrically nonlinear `S4/S4R -> FESA-MITC4`
- independence: FESA는 독립 solver이며 Abaqus 또는 Midas의 내부 알고리즘 동등성을 주장하지 않는다.
- unit_policy: `.inp` 단위계를 추론하거나 변환하지 않고 사용자가 일관되게 제공한 단위계를 보존한다.

Parent needs: `NEED-NSNR-001` nonlinear procedure, `NEED-NSNR-002` physics/numerical correctness,
`NEED-NSNR-003` state/output integrity, `NEED-NSNR-004` independent verification.

## 2. Purpose and Expected Behavior
FESA는 하나의 지원 nonlinear static step을 scalar load factor로 증가시키며 Full Newton–Raphson으로 각 증분의 평형을 구한다. 수렴한 증분만 atomically commit하고 authoritative accepted result로 기록한다. 기존 linear-static physics와 결과 의미는 보존하되 repository-wide derived output naming은 이 기능과 함께 적용할 승인 방향이다.

## 3. In Scope
- Abaqus source `S4`, `S4R`의 FESA-MITC4 mapping과 homogeneous isotropic linear elasticity
- fixed-initial-reference Total Lagrangian geometric nonlinearity와 finite rotational state
- same-trial residual/algorithmically consistent tangent, fresh factorization/solve의 Full Newton
- fixed scalar load-factor increments, common proportional load/BC path, fixed-global dead `*CLOAD`
- factor-1 absolute prescribed `*BOUNDARY` targets와 four-value nonlinear `*STATIC`
- four-channel residual/correction convergence, maximum 100 iterations, no line search
- separate trial state, atomic commit/rollback, accepted-frame HDF5와 per-iteration text log
- deterministic assembly, iteration, frame, result, diagnostic order와 factor-one global reaction/equilibrium 및 stored-reference verification

## 4. Out Of Scope
- material nonlinearity, nonlinear material history, combined material/geometric nonlinearity
- Updated Lagrangian, corotational procedure, multiple or mixed nonlinear steps, cross-step propagation
- follower load, non-proportional path, controlled-displacement, arc-length/path-following
- modified/adaptive Newton, tangent reuse, line search, damping, automatic growth/cutback/retry
- energy/work convergence, trial-state HDF5 history, direct reference-solver execution
- Abaqus/Midas formulation, stabilization, state update 또는 결과 절차의 내부 동등성

## 5. Analysis Definition
| item | approved meaning |
| --- | --- |
| analysis | exactly one nonlinear static step from a no-prior-history baseline |
| elements | `S4`, `S4R` source types map to materially linear FESA-MITC4 |
| DOFs | global `[UX, UY, UZ, URX, URY, URZ]`; rotational correction is dimensionless |
| kinematics | Total Lagrangian relative to one fixed initial configuration |
| rotation state | committed orthonormal right-handed triad `Q`; director is its third axis; separate trial triad/director; multiplicative finite-rotation update |
| material | homogeneous isotropic linear elasticity; no nonlinear material state |
| control | one dimensionless scalar load factor with fixed increments and final shortening to factor 1 |
| Newton | same-trial residual and consistent tangent, fresh factorization and correction solve every iteration |
| convergence | translational-force residual, rotational-moment residual, translational correction, rotational correction; all four must pass with `<=` |
| loads/BCs | fixed-global dead `*CLOAD`; factor-1 absolute `*BOUNDARY` targets on one proportional path |
| state | candidate/trial remains separate; complete converged increment commits atomically |
| coordinates/units | nodal values are global unless an approved element-local quantity states otherwise; user-consistent units without inference/conversion |

Exact Total Lagrangian shell equations, strain/stress measures, rotation map details, drilling treatment and consistent derivatives belong to Research/Formulation and Numerical Review without changing this approved scope.

## 6. Input Requirements
- Nonlinear execution requires exactly one supported nonlinear static source step and one semantic step.
- Supported first-release meanings are limited to the approved MITC4 material/section, nonlinear `*STATIC`, `*CLOAD`, and `*BOUNDARY` subset.
- Nonlinear `*STATIC` has four positive finite values: first is the fixed increment, second represents endpoint 1 exactly, and third/fourth are accepted for compatibility but unused by stepping.
- Nonzero prescribed `*BOUNDARY` values are factor-1 absolute global-DOF targets; approved `*CLOAD` components are fixed-global dead forces or moments.
- Unsupported, ambiguous, missing, nonfinite, or out-of-scope meanings fail closed rather than falling back to linear or alternate nonlinear behavior.

## 7. Output Requirements
- Successfully committed increments map one-to-one to authoritative accepted HDF5 frames in load-factor order and include the factor-1 frame; trial history is not authoritative output.
- `<stem>_results.h5` is completed as a sibling candidate and replaces the final only after success; failure preserves a prior valid final.
- `<stem>_log.txt` is replaced/truncated at invocation start and remains the current-run live audit after controlled success or failure.
- Every entered Newton iteration has one deterministic diagnostic-only text summary; exact representation and low-level I/O mechanics belong to I/O Definition.
- Every analysis procedure uses input-directory `<stem>_results.h5` and `<stem>_log.txt`; every invocation containing literal `--output` treats it as unrecognized and fails with exit code 2 before input parsing, Analysis, result-candidate, log, or output creation, with no compatibility alias or deprecation window. Result and log lifecycles are independent, not a cross-file all-or-nothing commit.
- Exact HDF5 paths/shapes, factor-0 projection, triad projection, compression/chunking and path/collision conventions belong to I/O Definition.

## 8. Requirement Records
```yaml
- id: FESA-REQ-NSNR-001
  statement: "The FESA solver shall execute nonlinear static analysis through a separate procedure only when exactly one supported nonlinear source step maps to exactly one semantic step from a no-prior-history baseline."
  category: functional
  rationale: "Procedure cardinality and lifecycle must be unambiguous."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "One valid step selects one nonlinear procedure; zero, multiple, mixed, or ambiguous nonlinear steps fail before an attempted nonlinear increment, while unselected approved linear analysis retains its established behavior."
  tolerance: "Exact source/semantic cardinality and procedure identity."
  trace_to: {parent_need: "NEED-NSNR-001", downstream_agents: ["I/O Definition Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-003
  statement: "The FESA solver shall support only materially linear, geometrically nonlinear FESA-MITC4 for source types S4 and S4R in the first release."
  category: physics
  rationale: "The approved release is geometric-only and must not create nonlinear material state."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Supported S4/S4R cases use homogeneous isotropic linear elasticity and MITC4; material-nonlinear or combined-nonlinearity input fails closed."
  tolerance: "Exact supported element/material inventory."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Research Agent", "Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-041
  statement: "The FESA solver shall use Total Lagrangian kinematics relative to one fixed initial reference configuration."
  category: physics
  rationale: "The formulation reference must not change across increments."
  source: user
  priority: must
  verification_method: analysis
  acceptance_criteria: "Every increment and accepted state retains the same initial-reference identity; current geometry is only a derived observable and never re-bases the formulation."
  tolerance: "Reference identity exact; numerical kinematic tolerances are owned by Numerical Review."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Research Agent", "Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-074
  statement: "The FESA solver shall retain global DOFs [UX, UY, UZ, URX, URY, URZ], use a dimensionless incremental rotation correction, and maintain separate trial and committed finite-rotation triad/director states."
  category: physics
  rationale: "Large rotations require an objective state distinct from failed candidates."
  source: user
  priority: must
  verification_method: analysis
  acceptance_criteria: "Committed Q is orthonormal and right-handed, its third axis is the director, candidate updates are multiplicative, successful commit transfers the complete state, and failure preserves the prior committed state."
  tolerance: "State identity exact; Q invariants use Numerical Review-approved tolerances."
  trace_to: {parent_need: "NEED-NSNR-002, NEED-NSNR-003", downstream_agents: ["Research Agent", "Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-006
  statement: "The FESA solver shall perform Full Newton iterations using the same current-trial residual and algorithmically consistent tangent, followed by a fresh tangent factorization and correction solve."
  category: numerical
  rationale: "Residual, tangent, factorization, and correction must describe one trial state."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Each entered iteration records one trial identity shared by residual and tangent, factorizes that tangent after evaluation, and solves its correction with that fresh factorization before convergence or update."
  tolerance: "Trial/factorization identity and event order exact."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Formulation Agent", "Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-007
  statement: "The FESA solver shall accept an increment only when its free-DOF equilibrium residual and same-iteration free-DOF Newton correction gates all pass."
  category: numerical
  rationale: "Equilibrium and update size are both required convergence evidence."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "All four channel results are combined by logical AND; constrained DOFs are excluded from convergence and their full-equilibrium residual retains reaction meaning."
  tolerance: "The four channel policies in NSNR-069 and NSNR-070 apply with inclusive <= comparisons."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-069
  statement: "The FESA solver shall evaluate translational-force and rotational-moment free-residual convergence with channel-separated infinity-norm gates selected by each matching external residual-channel scale."
  category: numerical
  rationale: "Force and moment dimensions require separate scales."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "For each residual channel, a nonzero matching external-channel scale retains denominator max(||internal||inf, ||external||inf), and the same-trial residual ratio passes iff <=1e-2; an exact-zero matching external-channel scale instead applies the typed absolute gate, which passes iff its numerator is <=1e-3 model-consistent force or <=1e-3 model-consistent force-length, respectively."
  tolerance: "Relative 1e-2 dimensionless for nonzero matching external-channel scale; exact-zero matching external-channel absolute 1e-3 force and 1e-3 force-length."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: draft
- id: FESA-REQ-NSNR-070
  statement: "The FESA solver shall evaluate translational and rotational free-correction convergence with channel-separated infinity-norm gates."
  category: numerical
  rationale: "Translation and rotation corrections have different dimensions."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "For a nonzero current-trial incremental-solution denominator relative to the step-start committed state, the fresh-correction ratio passes iff <=1e-2; an exact-zero denominator instead passes iff its numerator is <=1e-3 model-consistent length or <=1e-3 dimensionless rotation, respectively."
  tolerance: "Relative 1e-2 dimensionless; zero-scale absolute 1e-3 length and 1e-3 dimensionless rotation."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-008
  statement: "The FESA solver shall permit entered Newton iteration identities 1 through 100 and shall reject nonfinite required iteration data."
  category: numerical
  rationale: "The iteration limit and finite-data boundary must be deterministic."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "A pass at iteration 100 may commit; otherwise iteration 100 ends in nonconvergence without iteration 101, and any nonfinite required residual, tangent, correction, state, load, or recovery value fails before acceptance."
  tolerance: "Iteration identities and finite predicates exact."
  trace_to: {parent_need: "NEED-NSNR-002, NEED-NSNR-003", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-014
  statement: "The FESA solver shall apply each successful fresh Newton correction unchanged when another iteration is required and shall use no line search, damping, solver fallback, or energy/work convergence gate."
  category: constraint
  rationale: "The approved first release uses direct Full Newton updates only."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "The next candidate uses the fresh solve output without scalar or component modification; convergence depends only on NSNR-069 and NSNR-070."
  tolerance: "Correction/update identity exact."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-046
  statement: "The FESA solver shall advance one scalar load factor by a fixed positive increment, shortening only the final increment to reach factor one without growth, cutback, or retry."
  category: numerical
  rationale: "Fixed stepping provides the approved deterministic load path."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "The intended and accepted factor sequence starts at zero, never overshoots one, ends at the discrete factor-one identity on success, and analysis failure creates no replacement attempt."
  tolerance: "Factor/order identity exact; endpoint arithmetic is fixed by Numerical Review before implementation."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-048
  statement: "The FESA solver shall advance every approved CLOAD and nonzero prescribed BOUNDARY target on one common proportional scalar load-factor path."
  category: physics
  rationale: "Loads and prescribed values must share one path identity."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Factor zero reproduces step-start values, intermediate states use the same factor for all approved targets, and factor one reproduces every target."
  tolerance: "Load-factor and target identity exact."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-018
  statement: "The FESA solver shall interpret approved CLOAD force and moment components as dead loads fixed in global directions while the common factor scales magnitude only."
  category: physics
  rationale: "Follower-load behavior would change equilibrium and tangent meaning."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Force and moment source DOF directions remain unchanged with deformation, moments retain force-length dimensions, and no follower external-load tangent is used."
  tolerance: "Global component identity exact; values use the model-consistent unit system."
  trace_to: {parent_need: "NEED-NSNR-002", downstream_agents: ["Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-063
  statement: "The FESA solver shall interpret each approved nonzero BOUNDARY value as a factor-one absolute global-DOF target interpolated from its step-start committed value."
  category: physics
  rationale: "Absolute prescribed values must not be confused with correction increments."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "The prescribed current value follows the common factor, zero start/target remains zero, the constrained correction is distinct from that value, and failed candidates do not change the step-start value."
  tolerance: "Prescribed path/source identity exact; values use model-consistent displacement or rotation units."
  trace_to: {parent_need: "NEED-NSNR-002, NEED-NSNR-003", downstream_agents: ["Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-016
  statement: "The FESA solver shall map nonlinear STATIC four-value data with the first positive finite value as fixed increment, the second as endpoint one, and positive finite third and fourth values accepted but unused by stepping."
  category: input
  rationale: "The approved compatibility fields must not alter fixed stepping."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Valid four-value data records the first value for runtime use and identifies the third/fourth as unused; invalid arity, nonfinite/nonpositive required values, or period not representing one fails closed."
  tolerance: "Parsed endpoint-one identity exact; warning representation is owned by I/O Definition."
  trace_to: {parent_need: "NEED-NSNR-001", downstream_agents: ["I/O Definition Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-011
  statement: "The FESA solver shall keep trial state separate and atomically commit a complete converged displacement, rotation/director, load-factor, frame, force, and recovery state while preserving the prior committed state on failure."
  category: functional
  rationale: "Partial nonlinear state commits would corrupt continuation and results."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Successful validation commits one coherent state identity; iteration, increment, recovery, or output failure leaves the prior committed state and authoritative final result unchanged."
  tolerance: "State and commit identity exact."
  trace_to: {parent_need: "NEED-NSNR-003", downstream_agents: ["Formulation Agent", "Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-019
  statement: "The FESA solver shall preserve stable source identity and stable assembly order and shall keep the accepted free residual, constrained reaction resultant, and global applied-plus-reaction balance error as distinct equilibrium quantities derived at the same accepted state."
  category: physics
  rationale: "Reaction and equilibrium evidence must remain traceable without treating physically distinct projections as interchangeable."
  source: docs
  priority: must
  verification_method: test
  acceptance_criteria: "Input instance/label/component maps deterministically through assembly, state, diagnostic, result, and comparison; accepted free entries remain free-equilibrium evidence, constrained entries form physical reactions, and the constrained-reaction resultant remains distinct from the global applied-plus-reaction balance error. Blocking factor-one equilibrium quantities are global applied-plus-reaction force [3] and moment [3] balance errors plus accepted free residual. Every global moment is about global origin [0,0,0] and uses current force arms plus spatial physical nodal moments."
  tolerance: "Source/component, quantity identity, origin, and discrete order exact; equilibrium and reference values use their separately approved numerical tolerances."
  trace_to: {parent_need: "NEED-NSNR-002, NEED-NSNR-004", downstream_agents: ["Formulation Agent", "Numerical Review Agent", "I/O Definition Agent"]}
  status: approved
- id: FESA-REQ-NSNR-020
  statement: "The FESA solver shall fail closed on every input or model meaning outside the approved element, material, load, boundary, step, and solver scope."
  category: input
  rationale: "Unsupported nonlinear behavior must not become a warning-only or linear fallback."
  source: docs
  priority: must
  verification_method: test
  acceptance_criteria: "A negative inventory for each unsupported class rejects the model before nonlinear state or authoritative output is committed."
  tolerance: "Exact supported/unsupported inventory."
  trace_to: {parent_need: "NEED-NSNR-001", downstream_agents: ["I/O Definition Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-021
  statement: "The FESA solver shall create authoritative accepted HDF5 frames one-to-one with committed increments, including factor one, using a sibling candidate that replaces the final only on success and preserves a prior valid final on failure."
  category: output
  rationale: "Authoritative results must contain accepted states only and remain failure-safe."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Committed increment and accepted-frame identities match in factor order, the successful result includes factor one, trial Newton history is absent, and controlled failure does not expose the candidate as final or damage a prior valid final."
  tolerance: "Commit/frame identity exact; numerical quantities use their approved verification tolerances."
  trace_to: {parent_need: "NEED-NSNR-003", downstream_agents: ["Numerical Review Agent", "I/O Definition Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-024
  statement: "The FESA solver shall replace or truncate the single derived text log at invocation start, retain it as the current-run live audit on controlled success or failure, and produce one deterministic diagnostic-only summary for every entered Newton iteration."
  category: output
  rationale: "Iteration evidence is required without making trial states authoritative results."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Completed and early-failure iterations preserve their stable iteration/stage and convergence meaning in entered order; the log remains current-run diagnostic evidence and is not HDF5 trial history or reference data."
  tolerance: "Summary cardinality and semantic identity exact; representation and low-level failure presentation are owned by I/O Definition."
  trace_to: {parent_need: "NEED-NSNR-003", downstream_agents: ["I/O Definition Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-083
  statement: "The FESA solver shall apply repository-wide input-directory names <stem>_results.h5 and <stem>_log.txt, treat every invocation containing literal --output as unrecognized and fail it with exit code 2 before input parsing, Analysis, result-candidate, log, or output creation without a compatibility alias or deprecation window, and use independent asymmetric result/log lifecycles without cross-file all-or-nothing commit."
  category: output
  rationale: "Public output identity and authority must be consistent across procedures."
  source: user
  priority: must
  verification_method: test
  acceptance_criteria: "Every existing and future procedure derives the two approved names beside its input and preserves linear-static numerical/HDF5 meaning under the migration; every argument form containing literal --output fails as unrecognized with exit code 2 before input parsing, Analysis, result-candidate, log, or output creation and has no accepted alias or deprecation form; log initialization does not commit HDF5 and HDF5 failure does not roll back the live log."
  tolerance: "Names, exit code, lifecycle independence, and regression identity exact; path and ownership mechanics are downstream decisions."
  trace_to: {parent_need: "NEED-NSNR-003", downstream_agents: ["I/O Definition Agent", "Implementation Planning Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-026
  statement: "The FESA solver shall produce deterministic increment, iteration, assembly/reduction, accepted-frame, result-row, and diagnostic ordering for the same input and approved runtime configuration."
  category: constraint
  rationale: "Reproducible numerical and reference evidence requires stable discrete ordering."
  source: docs
  priority: must
  verification_method: test
  acceptance_criteria: "Repeated runs and approved thread configurations preserve the same intended/attempted/accepted factor identities, Newton event sequence, sparse/reduction structure, frame order, result identities, and log order."
  tolerance: "Discrete structure/order exact; floating equality policy is set by Numerical Review from repository conventions."
  trace_to: {parent_need: "NEED-NSNR-003, NEED-NSNR-004", downstream_agents: ["Numerical Review Agent", "Implementation Planning Agent"]}
  status: approved
- id: FESA-REQ-NSNR-030
  statement: "The FESA solver shall pass an approved verification portfolio covering the materially linear small-displacement limit, tangent consistency, factor-one global applied-plus-reaction balance and accepted free residual, symmetry or objectivity, and commit/rollback behavior."
  category: verification
  rationale: "Convergence alone does not establish nonlinear solver correctness."
  source: docs
  priority: must
  verification_method: analysis
  acceptance_criteria: "Numerical Review defines blocking cases and quantities for every listed category, and implementation passes each approved analytical, invariant, physics, or comparison gate. Reaction/equilibrium acceptance separately blocks on factor-one global applied-plus-reaction force [3] and moment [3] balance errors and accepted free-DOF residual evidence; constrained-reaction resultants retain a distinct identity, and local nodal reaction distribution does not decide the blocking verdict."
  tolerance: "Case-specific invariant tolerances are owned by Numerical Review; external comparisons use docs/TOLERANCE.md; existing linear-limit tolerance remains unchanged."
  trace_to: {parent_need: "NEED-NSNR-004", downstream_agents: ["Research Agent", "Formulation Agent", "Numerical Review Agent"]}
  status: approved
- id: FESA-REQ-NSNR-034
  statement: "The FESA solver shall compare only approved accepted-state quantities against stored reference artifacts using stable source/component matching, the approved blocking/warning/review disposition, and the common docs/TOLERANCE.md policy."
  category: verification
  rationale: "Reference acceptance must be deterministic and independent of solver execution."
  source: docs
  priority: must
  verification_method: reference-comparison
  acceptance_criteria: "Numerical Review selects the exact existing input and required CSV quantities; precheck rejects missing, extra, duplicate, or nonfinite required rows before numerical comparison, without averaging, collapse, row-order matching, zero clamp, or reference repair. U1/U2/U3 remain blocking and UR1/UR2/UR3 remain warning-only. Local nodal RF1/RF2/RF3 and physical spatial RM1/RM2 retain deterministic source-key/schema/finite/inventory/error reporting but are review-only and never change the blocking verdict; local RM3 and stress remain excluded from numerical comparison."
  tolerance: "docs/TOLERANCE.md family-scale policy for external blocking, warning-only, and review-only error reporting; exact artifact roles, local review projection, family membership, and row schema are a Numerical Review-owned readiness gap."
  trace_to: {parent_need: "NEED-NSNR-004", downstream_agents: ["Numerical Review Agent", "I/O Definition Agent"]}
  status: approved
```

## 9. Verification Quantities
| quantity | dimension / coordinates | role |
| --- | --- | --- |
| nodal displacement and committed rotation/director state | length and dimensionless rotation; global | accepted-state kinematics and rollback |
| accepted free-DOF residual | force or force-length; global DOF | blocking accepted-state equilibrium evidence |
| local nodal `RF1/RF2/RF3`, physical spatial `RM1/RM2` | force or force-length; global | deterministic review-only/nonblocking distribution evidence; `RM3` excluded |
| constrained-reaction resultant force `[3]` and moment `[3]` | force and force-length; global; moment about `[0,0,0]` with current arms and spatial physical moments | distinct reaction summary; not interchangeable with global balance error |
| applied-plus-reaction balance error force `[3]` and moment `[3]` | force and force-length; global; same origin/arm/moment convention | blocking factor-one reaction/equilibrium evidence |
| MITC4 internal force, stress and strain | model-consistent dimensions; approved element frame/configuration | formulation, physics and reference verification |
| scalar load factor and accepted frame identity | dimensionless | path, commit and output ordering |
| four convergence channels | typed as NSNR-069/070 | internal iteration acceptance only |
| iteration summary | diagnostic identity, not a physical reference quantity | convergence/failure audit |

## 10. Tolerance Policy
- `.inp` values remain in the user's consistent unit system; FESA performs no unit inference or conversion.
- Residual ratios with nonzero matching external-channel scale and correction ratios with nonzero current-trial incremental-solution denominator are dimensionless and pass with `<=1e-2`.
- Exact-zero matching external-channel residual thresholds are `1e-3` force and `1e-3` force-length; exact-zero correction-denominator thresholds are `1e-3` length and `1e-3` dimensionless rotation. Equal literals do not merge their dimensions.
- External blocking, warning-only, and review-only error reporting use `docs/TOLERANCE.md` without changing their verdict disposition; internal invariant, tangent, endpoint-arithmetic, free-residual and global-balance tolerances are fixed by Numerical Review before implementation.

## 11. Reference Case Requirements
- Stored nonlinear candidates use exact read-only input/displacement pairs `reference/shellNL/shellNL.inp` with `reference/shellNL/shellNL displacements.csv`, and `reference/shellNL-meshfine/shellNL-meshfine.inp` with `reference/shellNL-meshfine/shellNL-meshfine displacements.csv`. Exact local-reaction review artifacts are `reference/shellNL/shellNL reactions.csv` and `reference/shellNL-meshfine/shellNL-meshfine reactions.csv`; they are not missing-required blocking artifacts. The existing linear-limit pair is `reference/shell/shell.inp` and `reference/shell/shell displacements.csv`.
- Numerical Review shall fix which exact nonlinear candidate case or cases are blocking versus diagnostic, the factor-one HDF5 projection, required source rows/components and comparison families, and the internal tolerances for global balance/free-residual gates. `U1/U2/U3` are blocking, `UR1/UR2/UR3` are warning-only, local nodal RF/RM rows are review-only, and `RM3` and stress have no numerical comparison projection.
- All selected local review rows retain deterministic identity, schema, finite-value, inventory, and error reporting even though they cannot fail the blocking verdict. A physical global resultant sum is not a substitute identity for those local rows, and no row is averaged, collapsed, omitted, zero-clamped, or repaired.
- Agents do not run Abaqus, Nastran or another reference solver and do not create, rename, repair or normalize stored reference artifacts.

## 12. Requirement Verification Matrix
| id | category | source | priority | method | compact acceptance | tolerance | downstream | status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `NSNR-001` | functional | user | must | test | exactly one supported source/semantic nonlinear step | exact cardinality | I/O; Planning | approved |
| `NSNR-003` | physics | user | must | test | MITC4 geometric-only, linear isotropic material | exact inventory | Research; Formulation; Numerical Review | approved |
| `NSNR-041` | physics | user | must | analysis | fixed initial reference, no re-basing | identity exact | Research; Formulation; Numerical Review | approved |
| `NSNR-074` | physics | user | must | analysis | finite committed/trial triad/director state and rollback | invariant tolerance downstream | Formulation; Numerical Review | approved |
| `NSNR-006` | numerical | user | must | test | same-trial residual/tangent and fresh factorization/solve | identity/order exact | Formulation; Numerical Review; Planning | approved |
| `NSNR-007` | numerical | user | must | test | all four free-DOF gates pass; constrained residual is reaction | NSNR-069/070 | Numerical Review; Planning | approved |
| `NSNR-069` | numerical | user | must | test | force/moment residual relative gate for nonzero external scale; typed absolute gate for exact-zero external scale | `1e-2`; typed `1e-3` | Numerical Review; Planning | draft |
| `NSNR-070` | numerical | user | must | test | translation/rotation correction relative or typed zero-scale gates | `1e-2`; typed `1e-3` | Numerical Review; Planning | approved |
| `NSNR-008` | numerical | user | must | test | finite data, iterations 1..100, pass at 100 allowed | predicates/count exact | Numerical Review; Planning | approved |
| `NSNR-014` | constraint | user | must | test | unchanged full correction; no line search/fallback/energy gate | identity exact | Numerical Review; Planning | approved |
| `NSNR-046` | numerical | user | must | test | fixed increment, final shortening, no retry | factor/order exact | Numerical Review; Planning | approved |
| `NSNR-048` | physics | user | must | test | one proportional factor for all load/BC targets | identity exact | Formulation; Numerical Review | approved |
| `NSNR-018` | physics | user | must | test | fixed-global dead force/moment and no follower tangent | component exact | Formulation; Numerical Review | approved |
| `NSNR-063` | physics | user | must | test | absolute factor-one BC target and separate correction | path/source exact | Formulation; Numerical Review | approved |
| `NSNR-016` | input | user | must | test | four-value STATIC mapping and validation | endpoint exact | I/O; Planning | approved |
| `NSNR-011` | functional | user | must | test | separate trial, atomic commit, prior-state preservation | state exact | Formulation; Numerical Review; Planning | approved |
| `NSNR-019` | physics | docs | must | test | distinct free residual, constrained-reaction resultants and applied+reaction balance; current-arm/spatial-moment semantics | quantity/origin/identity/order exact | Formulation; Numerical Review; I/O | approved |
| `NSNR-020` | input | docs | must | test | unsupported meaning fails closed | inventory exact | I/O; Planning | approved |
| `NSNR-021` | output | user | must | test | accepted commit/frame bijection and failure-safe HDF5 final | identity exact | Numerical Review; I/O; Planning | approved |
| `NSNR-024` | output | user | must | test | one ordered diagnostic summary per entered iteration and persistent live log | semantic identity exact | I/O; Planning | approved |
| `NSNR-083` | output | user | must | test | repository names; every literal --output form unrecognized with pre-input/pre-Analysis/pre-output exit 2 and no alias/deprecation; asymmetric lifecycle; linear regression | public identity/precedence exact | I/O; Planning; Numerical Review | approved |
| `NSNR-026` | constraint | docs | must | test | deterministic factor/iteration/assembly/frame/result/log order | discrete order exact | Numerical Review; Planning | approved |
| `NSNR-030` | verification | docs | must | analysis | blocking small-limit/tangent/global applied+reaction balance/free-residual/physics/rollback portfolio | case-specific downstream; external policy unchanged | Research; Formulation; Numerical Review | approved |
| `NSNR-034` | verification | docs | must | reference-comparison | U blocking, UR warning-only, local RF/RM review-only, exact matching/precheck | docs/TOLERANCE.md | Numerical Review; I/O | approved |

## 13. Open Questions
없음. Specialist gaps are owned by downstream stages and are escalated only if they would change approved scope, physics, tolerance, authoritative output or public compatibility.

## 14. Downstream Handoff
- Research/Formulation: exact Total Lagrangian MITC4 equations, strain/stress measures, rotation map/side/frame, drilling and consistent derivatives; Formulation propagates NSNR-069's exact-zero matching external-channel typed absolute branch and retained nonzero external-scale relative denominator.
- Numerical Review: verify the revised NSNR-069 branch and unchanged thresholds/four-channel AND, endpoint arithmetic, tangent/objectivity/state-invariant checks, benchmark portfolio and performance adequacy. Fix exact coarse/fine reference roles, local review projection/families, and factor-one global balance/free-residual tolerances while preserving local RF/RM review-only, `RM3` exclusion, displacement/rotation disposition, exact prechecks, immutable artifacts and common external tolerance.
- I/O Definition: HDF5 schema/projection/chunking/factor-0 handling, log representation/failure presentation and path/collision conventions. Audit and keep separately identifiable `(a)` global applied-plus-reaction balance error, `(b)` constrained-reaction resultant and `(c)` accepted free residual; global moments use current positions and spatial physical nodal moments about `[0,0,0]`, including supported nonzero prescribed translation/rotation cases.
- Implementation Planning: backend adapters, output ownership primitive, candidate filename, performance targets and requirement-traced TDD plan. Stage 6 must test the three equilibrium identities separately and must not reuse one implementation dataset as another without proving its approved projection semantics.
- Coordinator: escalate only a downstream proposal that changes the approved scope, physics, convergence tolerance, authoritative-result meaning or public output contract; do not advance the workflow on this document alone.