FESADev/docs/superpowers/specs/2026-08-12-independent-reference-validation-policy-design.md

# Independent Reference Validation Policy Design

## Status

- date: `2026-08-12`
- amended_on: `2026-08-18`
- status: `approved`
- scope: FESA project policy, agents, skills, and `linear-static-mitc4-shell` upstream contracts
- implementation_code: out of scope
- reference_artifact_mutation: prohibited

2026-08-18 amendment: the former MITC4 fixed absolute tolerance is superseded by the common
family-scale row/RMS policy in `2026-08-17-common-reference-tolerance-design.md` and ADR-022.
The independent-solver, minimal-reference-case and drilling decisions remain unchanged.

## Decision

FESA is an independent finite element solver. It accepts an approved subset of the
Abaqus `.inp` syntax, but it does not reproduce or claim equivalence with Abaqus
element formulations, integration rules, stabilization, internal state, or result
generation procedures. Abaqus CSV values are external numerical reference values.
Exact equality is allowed but is neither required nor evidence of identical internal
behavior.

A feature passes reference verification when FESA solves the declared input and its
required comparison quantities satisfy the feature-approved tolerance. Reference
artifact governance that does not participate in that comparison must not block
implementation planning or verification.

## Minimal Reference Case Contract

A reference case requires only:

- the declared `.inp` file used by both solvers;
- the declared Abaqus CSV file for each blocking or warning-only quantity;
- the FESA `results.h5` produced from that `.inp`;
- a deterministic mapping of the compared source identity and components;
- the approved tolerance.

The following are not readiness requirements:

- canonical directory or filename conventions;
- legacy-alias approval;
- bundle `README.md`;
- `metadata.json`;
- Abaqus version or generation provenance;
- duplicated unit, coordinate, model, step, final-frame, material, thickness, or
  element-type metadata;
- a reference CSV schema version.

Reference paths and filenames are consumed as declared without rename or repair.
Reference artifacts remain read-only. A comparator must still reject ambiguous or
unsafe comparisons: missing files, missing required source IDs/components, duplicate
IDs, unmatched required rows, and nonfinite values. This is an executable matching
contract, not a metadata or bundle-governance contract.

For a feature with one supported static step and one final frame, the input/CSV pair
implicitly identifies that result state. Model properties and source element types are
read from the `.inp` rather than copied into another metadata file.

## Reference Model Phase

The Reference Model phase remains in the workflow as a lightweight reference-case
inventory. It records:

- the purpose of each existing case;
- exact input and required CSV paths;
- blocking and warning-only quantities;
- FESA HDF5 projection and source-ID/component matching;
- the approved tolerance;
- whether the required files are present and readable.

It does not design a broad benchmark portfolio unless the feature requirements
explicitly request one. It does not gate on naming, README, metadata, provenance, or
duplicated descriptive fields.

## MITC4 Reference Acceptance

Both source element types map to the same internal `FESA-MITC4` formulation, but the
2026-08-13 feature-scope amendment uses only the full-integration S4 case for Abaqus
acceptance comparison:

- `reference/shell/shell.inp` and `reference/shell/shell displacements.csv` cover
  source `S4`;
- source `S4R` is covered by parser/common-kernel/deterministic-assembly/HDF5 metadata
  tests without consuming an Abaqus S4R artifact.

Only matched global `U1/U2/U3` rows are blocking. `UR1/UR2/UR3` rows are compared and
reported as warning-only evidence. Reactions and stresses may be inspected but are not
reference pass/fail quantities.

The project-wide common policy now evaluates each matched U/UR component family:

```text
S = max(abs(reference_value_i))
near_zero_i = abs(reference_value_i) <= 0.01 * S
ordinary_row_pass_i = abs(error_i) / abs(reference_value_i) <= 0.05
near_zero_row_pass_i = abs(error_i) <= 0.01 * S
relative_rms = sqrt(mean(error_i^2)) / S <= 0.01
```

The scale is computed from read-only reference values in the same model, step/frame,
quantity and component family. If `S == 0`, only exact-zero FESA values pass; otherwise
the reason is `zero-reference-scale-nonzero-error`. There is no independent absolute-error
gate. Values are not zero-clamped. Missing, duplicate, unmatched, or nonfinite required
rows fail before numeric tolerance evaluation. U tolerance failure fails reference
verification; UR tolerance exceedance emits a deterministic warning only. B33 uses the
same row and family-RMS thresholds.

No additional locking, convergence, distorted, curved, director-angle, or invalid
geometry reference portfolio is required for this MITC4 implementation acceptance.
The previously open `NR-O03` and `NR-O04` calibration/inspection requirements are
removed from the feature gate.

## MITC4 Drilling Boundary

Drilling calibration is excluded, but a fixed numerical stabilization remains required
to make the external six-DOF shell system solvable. The feature does not implement a
physical drilling strain or accept director-parallel nodal moments.

Use one element-level scalar computed from the positive diagonal entries of the
physical rotational stiffness block:

```text
k_d = 1e-3 * min(K_phys[i,i] | i is a physical rotational DOF and K_phys[i,i] > 0)
K_drill_local = k_d * I4
K_drill_global = T_d^T * K_drill_local * T_d
```

Restricting the minimum to rotational entries preserves the `force*length` dimension.
The literal minimum over mixed translational and rotational diagonals is not approved.
The stabilization must be finite, symmetric, positive, deterministic, and excluded
from physical generalized strain, resultant, and stress recovery.

The following are out of scope:

- reference-family selection and `rho_d` normalization;
- coefficient sweeps, stable plateaus, rank/conditioning calibration, and adjacent
  decade sensitivity;
- drilling-to-physical energy thresholds or warning policies;
- mandatory drilling stiffness, ratio, or energy result datasets.

Basic unit tests may verify construction, symmetry, positivity, deterministic behavior,
and removal of the four nonphysical drilling null modes. Current reference cases contain
no drilling-direction load; their blocking safeguard against unacceptable physical
response contamination is the approved U comparison.

## Numerical Review Boundary

Numerical Review decides whether the documented formulation is internally complete and
consistent enough to plan implementation. It must not fail because a later Reference
Model document, canonical bundle, README, metadata, provenance, extended benchmark
portfolio, or comparison result is absent.

For MITC4:

- fixed drilling stabilization closes `NR-O01` and removes `NR-O02` by scope;
- `NR-O03` and `NR-O04` are removed from the approved verification scope;
- the common family-scale row/RMS policy closes the blocking part of `NR-O05`;
- missing heavyweight reference metadata is `not-required-by-policy`;
- confirmed formulation defects remain blocking.

## Agent and Skill Workflow

Requirement, I/O, Reference Model, Reference Verification, Coordinator, Implementation
Planning, Physics Evaluation, and Release instructions must use the minimal reference
case contract. Numerical Review must remain independent of later artifact governance.

Implementation Planning must use the project-local `harness` skill when the user asks
for an implementation plan. It must:

1. prepare a multi-Step draft with one layer or module per Step;
2. make each Step self-contained for an independent Codex execution;
3. include prerequisite documents, TDD RED/GREEN/VERIFY work, exact MSVC/CMake/CTest
   acceptance commands, and specific prohibitions;
4. request user approval for the Step draft;
5. only after approval create or update `phases/index.json`,
   `phases/<task-name>/index.json`, and `phases/<task-name>/stepN.md`;
6. leave Harness execution to an explicit subsequent user request.

## Scope Preservation

- Do not modify files under `reference/`.
- Do not run Abaqus or another reference solver.
- Do not add C++ MITC4 implementation in this policy-alignment change.
- Keep the future geometric-nonlinear residual/tangent derivation documentation, but do
  not authorize nonlinear product execution.
- Historical research evidence may retain its original cautions. Current requirements,
  formulation decisions, I/O contracts, and the latest numerical review must clearly
  identify the approved policy that supersedes earlier recommendations.