# 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: - `reference/shell/shell.inp` and `reference/shell/shell displacements.csv` cover source `S4`; - `reference/shellR/shellR.inp` and `reference/shellR/shellR displacements.csv` cover source `S4R`. 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 each case and component `c`: ```text reference_scale_c = max_i(abs(abaqus_value_i,c)) tolerance_c = 1e-9 + 1e-6 * reference_scale_c ``` The `1e-9` absolute floor is expressed in the model's user-consistent length unit for translation and as a dimensionless rotation value for warning-only UR. 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. 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 B33 mixed tolerance 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//index.json`, and `phases//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.