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

Independent Reference Validation Policy Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Align FESA project policy and the MITC4 upstream contracts with independent black-box Abaqus reference validation and prepare the implementation-planning agent to create approved Harness Steps.

Architecture: Keep FESA HDF5 as authoritative solver output and retain deterministic source-node/component comparison, while reducing the reference phase to a lightweight inventory of existing .inp and required CSV paths. Remove metadata, naming, portfolio, drilling-calibration, and geometry/director-calibration gates from MITC4 without changing reference artifacts or implementing C++.

Tech Stack: Markdown, TOML agent prompts, project-local Codex SKILL.md, PowerShell static validation, Git.

Global Constraints

• Do not modify files under reference/.
• Do not run Abaqus or another reference solver.
• Do not modify C++ source, tests, or CMake.
• Preserve HDF5 as authoritative FESA output.
• Use fixed absolute 1.0e-5 for MITC4 U/UR; U blocks and UR warns only. Keep the separate B33 mixed tolerance unchanged.
• Retain fixed numerical drilling stabilization but exclude calibration and drilling evidence outputs.
• Remove NR-O03 and NR-O04 from MITC4 implementation readiness.
• Implementation Planning may create Harness phase files only after user approval of the Step draft.

---

Task 1: Align project-wide policy documents

Files:

• Modify: AGENTS.md
• Modify: docs/PRD.md
• Modify: docs/ADR.md
• Modify: docs/ARCHITECTURE.md
• Modify: docs/SOLVER_AGENT_DESIGN.md
• Modify: docs/SOLVER_SKILL_DESIGN.md

Interfaces:

• Consumes: approved design in docs/superpowers/specs/2026-08-12-independent-reference-validation-policy-design.md

• Produces: project-wide independent-solver and minimal-reference policy used by every downstream agent

• Replace canonical/legacy/provenance bundle governance with the minimal reference-case contract.

• Separate Abaqus input syntax and external comparison from FESA formulation behavior.

• Record the new decision as a superseding ADR while preserving historical decisions.

• State the MITC4 fixed absolute tolerance and fixed drilling scope without claiming implementation exists.

• Verify changed policy terms with targeted rg checks and git diff --check.

• Commit with docs: simplify FESA reference validation policy.

Task 2: Align agent and skill workflow contracts

Files:

• Modify: affected .codex/agents/*.toml
• Modify: affected .codex/skills/*/SKILL.md
• Modify: affected workflow README templates under docs/

Interfaces:

• Consumes: Task 1 project policy

• Produces: specialist prompts that no longer recreate removed artifact gates

• Update Requirement, Numerical Review, I/O, Reference Model, Reference Verification, Coordinator, Implementation Planning, Physics, and Release boundaries.

• Require Implementation Planning Agent to invoke $harness, produce a self-contained multi-Step draft, request user approval, and only then write phases/ files.

• Keep actual Harness execution outside the planning agent unless explicitly requested.

• Validate TOML syntax, skill YAML frontmatter, required sections, and prohibited stale terms.

• Forward-test the revised skills with an independent agent prompt.

• Commit with docs: align FESA agents with minimal reference cases.

Task 3: Revise MITC4 requirements and formulation

Files:

• Modify: docs/requirements/linear-static-mitc4-shell.md
• Modify: docs/research/linear-static-mitc4-shell-research.md
• Modify: docs/formulations/mitc4-shell-formulation.md

Interfaces:

• Consumes: Tasks 1-2 policy and approved fixed drilling rule

• Produces: implementation-ready feature scope without removed calibration gates

• Correct the observed S4/S4R reference inventory and adopt fixed absolute 1.0e-5 for MITC4 U/UR.

• Replace drilling candidate/sweep language with the fixed positive rotational-diagonal rule.

• Remove drilling calibration, drilling-energy warning, NR-O03, NR-O04, and expanded portfolio requirements.

• Preserve the future nonlinear derivation as documentation-only.

• Add a research decision note without rewriting source findings as if they changed.

• Verify requirement IDs and formulation traceability contain no contradictory blocker.

• Commit with docs: simplify MITC4 verification and drilling scope.

Task 4: Revise MITC4 I/O and reference-case inventory

Files:

• Modify: docs/io-definitions/linear-static-mitc4-shell-io.md
• Create: docs/reference-models/linear-static-mitc4-shell-reference-models.md

Interfaces:

• Consumes: Task 3 requirements/formulation

• Produces: exact lightweight full-integration S4 input-to-displacement-CSV pairing and HDF5 comparison mapping; S4R non-reference coverage

• Remove canonical/legacy/metadata/provenance/schema-version readiness requirements.

• Remove mandatory drilling stiffness, ratio, and energy output evidence.

• Keep minimal source-node plus U/UR component matching and finite/unique-row checks.

• Inventory only the exact existing reference/shell S4 paths as acceptance inputs; keep reference/shellR optional and read-only without consuming it.

• Verify no file under reference/ changed.

• Commit with docs: define lightweight MITC4 reference cases.

Task 5: Rerun MITC4 numerical review under the approved policy

Files:

• Modify: docs/numerical-reviews/linear-static-mitc4-shell-review.md

Interfaces:

• Consumes: Tasks 1-4 current source-of-truth documents

• Produces: a fresh formulation-only implementation-planning verdict

• Reclassify removed artifact, calibration, NR-O03, and NR-O04 blockers explicitly.

• Review the fixed rotational-diagonal drilling rule for dimensions, symmetry, positivity, and separation from physical recovery.

• Confirm U/UR tolerance and current S4/S4R reference pairing are downstream comparison inputs, not formulation blockers.

• Issue the verdict supported by the remaining confirmed formulation findings only.

• Run Markdown structure, targeted policy consistency, git diff --check, and no-reference-mutation checks.

• Commit with docs: rerun MITC4 numerical review under minimal reference policy.

Task 6: Final repository policy verification

Files:

• Verify: all files changed by Tasks 1-5

Interfaces:

• Consumes: all preceding tasks

• Produces: clean, internally consistent documentation and agent/skill configuration evidence

• Run uv run --with pytest python -m pytest -v -rs because project-local agent/skill workflow documents changed.

• Parse every changed TOML file and validate every changed skill frontmatter.

• Run repository-wide targeted searches for stale mandatory provenance, canonical, README, drilling sweep, NR-O03, and NR-O04 language in active contracts.

• Run git diff --check and inspect git status --short.

• Confirm git diff -- reference is empty.

• Report any historical documents intentionally left unchanged.