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

Independent Reference Validation Policy Design

Status

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

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.

For every matched U/UR row:

tolerance = 1.0e-5

The fixed value is expressed in the model's user-consistent length unit for translation and as a dimensionless rotation value for warning-only UR. Reference scale may remain diagnostic report data but does not enter the tolerance or normalized-error denominator. 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. The B33 mixed tolerance remains unchanged.

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:

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 fixed absolute MITC4 tolerance 1.0e-5 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.