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/linear-static-mitc4-shell/requirements.md`
- Modify: `docs/linear-static-mitc4-shell/research.md`
- Modify: `docs/linear-static-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/linear-static-mitc4-shell/io.md`
- Create: `docs/linear-static-mitc4-shell/reference-model.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/linear-static-mitc4-shell/numerical-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.