docs: redefine phase 1 rebaseline steps

2026-05-04 12:15:07 +09:00
parent a385235e14
commit 357b4bd893
20 changed files with 1013 additions and 18 deletions
@@ -0,0 +1,22 @@
+{
+  "project": "FESA",
+  "phase": "1-linear-static-mitc4-rebaseline",
+  "steps": [
+    { "step": 0, "name": "rebaseline-audit", "status": "pending" },
+    { "step": 1, "name": "reference-onboarding", "status": "pending" },
+    { "step": 2, "name": "core-harness-guardrails", "status": "pending" },
+    { "step": 3, "name": "parser-domain-subset", "status": "pending" },
+    { "step": 4, "name": "validation-singular-diagnostics", "status": "pending" },
+    { "step": 5, "name": "dof-manager-reaction-foundation", "status": "pending" },
+    { "step": 6, "name": "results-comparator-foundation", "status": "pending" },
+    { "step": 7, "name": "mitc4-geometry-directors", "status": "pending" },
+    { "step": 8, "name": "mitc4-covariant-strain-tying", "status": "pending" },
+    { "step": 9, "name": "mitc4-material-integration", "status": "pending" },
+    { "step": 10, "name": "mitc4-stiffness-drilling", "status": "pending" },
+    { "step": 11, "name": "mitc4-patch-benchmark-tests", "status": "pending" },
+    { "step": 12, "name": "assembly-sparse-solver-path", "status": "pending" },
+    { "step": 13, "name": "linear-static-workflow", "status": "pending" },
+    { "step": 14, "name": "stored-reference-regression", "status": "pending" },
+    { "step": 15, "name": "phase1-evaluator-closeout", "status": "pending" }
+  ]
+}
@@ -0,0 +1,59 @@
+# Sprint Contract: Rebaseline Audit
+
+## Objective
+Audit the existing Phase 1 implementation against the paper-based `docs/MITC4_FORMULATION.md` and produce a concrete rework map before changing solver behavior.
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/PRD.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/MITC4_FORMULATION.md
+- /phases/1-linear-static-mitc4/index.json
+
+## Scope
+- Inspect existing C++ implementation and tests only enough to classify what can be retained, rewritten, or deleted in later steps.
+- Produce or update planning notes in `PLAN.md` and `PROGRESS.md`.
+- If useful, add a short audit artifact under `phases/1-linear-static-mitc4-rebaseline/`.
+
+## Allowed Files
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4-rebaseline/`
+
+## Explicit Non-Goals
+- Do not change production C++ behavior.
+- Do not rewrite MITC4 formulas.
+- Do not unblock stored-reference regression by accepting unsupported Abaqus syntax.
+
+## Tests To Write First
+- None. This is a planning and audit sprint.
+
+## Reference Artifacts
+- `references/quad_01.inp`
+- `references/quad_01_displacements.csv`
+- `references/quad_02.inp`
+- `references/quad_02_displacements.csv`
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- The audit identifies conflicts with `docs/MITC4_FORMULATION.md`, especially old averaged-edge basis, `1.0e-6` drilling scale, analytic thickness integration, and direct shear evaluation risks.
+- Future work is assigned to later rebaseline steps instead of being fixed here.
+- `PLAN.md` and `PROGRESS.md` describe the new state without treating the old P1-01 through P1-14 implementation as authoritative.
+
+## Handoff Requirements
+- Record completed audit work in `PROGRESS.md`.
+- Keep next implementation tasks in `PLAN.md` or later step files.
+
+## Do Not
+- Do not merge this audit with implementation.
+- Do not remove old phase history.
@@ -0,0 +1,61 @@
+# Sprint Contract: Reference Onboarding
+
+## Objective
+Create a Phase 1 reference path for `quad_02` without modifying the original Abaqus artifact or silently expanding parser support.
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/RESULTS_SCHEMA.md
+- /docs/MITC4_FORMULATION.md
+- /references/quad_02.inp
+- /references/quad_02_displacements.csv
+
+## Scope
+- Inspect `quad_02` and document its supported and unsupported features.
+- Add a normalized Phase 1-compatible derivative input if selected by the planner, keeping the original `quad_02.inp` unchanged.
+- Add notes or manifest metadata for unit system, source solver, expected outputs, and tolerances.
+
+## Allowed Files
+- `references/`
+- `docs/ABAQUS_INPUT_SUBSET.md`
+- `docs/VERIFICATION_PLAN.md`
+- `PLAN.md`
+- `PROGRESS.md`
+- `tests/` only for reference artifact parsing/comparator tests
+
+## Explicit Non-Goals
+- Do not implement `Part`, `Assembly`, or `Instance` parser support in this step unless this contract is revised first.
+- Do not edit `references/quad_02.inp` or `references/quad_02_displacements.csv`.
+- Do not compare solver displacements until the MITC4 rebuild and end-to-end workflow are complete.
+
+## Tests To Write First
+- Test that original `quad_02.inp` is recognized as stored provenance with unsupported `Part/Assembly/Instance`.
+- If a normalized input is added, test that it contains only the documented Phase 1 subset.
+- Test `quad_02_displacements.csv` column loading and 121-row node-label parsing.
+
+## Reference Artifacts
+- `references/quad_02.inp`
+- `references/quad_02_displacements.csv`
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Original Abaqus files are preserved.
+- Any normalized derivative file has a clear name and provenance note.
+- Parser scope remains aligned with `docs/ABAQUS_INPUT_SUBSET.md`.
+- Tolerances and result mapping are documented before regression use.
+
+## Handoff Requirements
+- Update `PROGRESS.md` with reference files changed or added.
+- Update `PLAN.md` if parser compatibility remains blocked.
+
+## Do Not
+- Do not treat `*Density` as material support.
+- Do not allow `Part/Assembly/Instance` through the Phase 1 parser accidentally.
@@ -0,0 +1,54 @@
+# Sprint Contract: MITC4 Stiffness Drilling
+
+## Objective
+Assemble the MITC4 element stiffness and internal force kernel using the documented strain, material, integration, six-DOF transform, and drilling stabilization.
+
+## Required Reading
+- /AGENTS.md
+- /docs/MITC4_FORMULATION.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ADR.md
+
+## Scope
+- Accumulate `K_e = integral B^T D B dV`.
+- Add local drilling stabilization with `drilling_stiffness_scale = 1.0e-3`.
+- Transform local element stiffness/internal force to global 24-DOF order.
+- Preserve parameterization and diagnostics for drilling scale.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not add assembly/global solve.
+- Do not tune drilling scale to match one reference case.
+- Do not output stresses/resultants as mandatory fields.
+
+## Tests To Write First
+- Stiffness dimension and symmetry tests.
+- Drilling diagonal reference tests using minimum positive physical local stiffness diagonal.
+- Zero/invalid reference diagonal diagnostic tests.
+- Rigid body physical strain-energy tests with documented drilling effects.
+- Internal force consistency test `f_int_e = K_e u_e` for linear elastic Phase 1.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Old `1.0e-6 * E * thickness` drilling rule is gone.
+- Global 24-DOF ordering matches `UX,UY,UZ,RX,RY,RZ` per node.
+- Stiffness remains linear elastic and symmetric.
+
+## Handoff Requirements
+- Record element kernel readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not optimize or parallelize before element tests pass.
@@ -0,0 +1,52 @@
+# Sprint Contract: MITC4 Patch Benchmark Tests
+
+## Objective
+Add element-level and small-mesh MITC4 patch and benchmark tests before integrating stored Abaqus references.
+
+## Required Reading
+- /AGENTS.md
+- /docs/MITC4_FORMULATION.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/NUMERICAL_CONVENTIONS.md
+
+## Scope
+- Add constant membrane, pure bending, pure shear, pure twist, rigid-body, and drilling sensitivity tests.
+- Add a thin cantilever or plate strip test to expose shear locking.
+- Add benchmark scaffolding for Scordelis-Lo after flat tests pass.
+
+## Allowed Files
+- `tests/`
+- `include/`
+- `src/` only for minimal fixes required by tests
+- `docs/VERIFICATION_PLAN.md` only for clarifying benchmark notes
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not require Abaqus execution.
+- Do not add pressure loads for Scordelis-Lo in Phase 1.
+- Do not hide failing element behavior by loosening tolerances without rationale.
+
+## Tests To Write First
+- The patch and benchmark tests are the sprint output; write them before any fixes.
+- Include at least one negative or sensitivity test for drilling scale effects.
+
+## Reference Artifacts
+- Local analytic or hand-check benchmark data only.
+- Stored Abaqus CSV regression is reserved for step 14.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Tests cover locking-sensitive behavior, not only shape functions.
+- Tolerances are scale-aware and documented.
+- Any implementation fixes remain minimal and within MITC4 scope.
+
+## Handoff Requirements
+- Record benchmark coverage and remaining gaps in `PROGRESS.md` and `PLAN.md`.
+
+## Do Not
+- Do not implement new load types to force a benchmark into Phase 1.
@@ -0,0 +1,55 @@
+# Sprint Contract: Assembly Sparse Solver Path
+
+## Objective
+Rebuild or verify full-space assembly, reduced free-DOF solve path, solver adapter boundary, and full-vector reaction recovery using the rebuilt MITC4 kernel.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/MITC4_FORMULATION.md
+
+## Scope
+- Assemble global stiffness and external load vectors.
+- Preserve full-space data for `RF = K_full * U_full - F_full`.
+- Apply constrained DOF elimination via `DofManager`.
+- Use the current deterministic test solver or adapter boundary; keep MKL behind a future adapter.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not expose MKL or TBB APIs directly in solver core.
+- Do not compare stored Abaqus references yet.
+- Do not compute reactions from reduced equations.
+
+## Tests To Write First
+- Small assembled system tests with known displacement.
+- Full-vector `RF` recovery tests.
+- Constrained/free projection tests through assembly.
+- Singular solve diagnostic tests.
+- Sparse pattern deterministic ordering tests if sparse structure exists.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Full-space stiffness/load/displacement are available or reconstructable for reactions.
+- Solver adapter boundary is preserved.
+- Singular failures remain actionable.
+
+## Handoff Requirements
+- Record assembly and reaction readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not let elements own global equation ids.
@@ -0,0 +1,56 @@
+# Sprint Contract: Linear Static Workflow
+
+## Objective
+Rebuild or verify the full linear static workflow from parsed `Domain` to `AnalysisModel`, `AnalysisState`, solve, `U` and `RF` result fields.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/RESULTS_SCHEMA.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/MITC4_FORMULATION.md
+
+## Scope
+- Build the active `AnalysisModel` for one linear static step.
+- Run the template workflow: build DOF map, assemble, apply constraints, solve, reconstruct full vectors, recover RF, write results.
+- Keep `Domain` immutable and `AnalysisState` mutable.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not implement nonlinear, dynamic, pressure, or thermal behavior.
+- Do not add multiple-step execution unless already trivial and tested.
+- Do not make HDF5 dependency mandatory if the current minimal writer remains the accepted Phase 1 path.
+
+## Tests To Write First
+- Input-to-analysis-model activation test.
+- End-to-end small linear static solve with `U` and `RF`.
+- Result schema field label and frame tests.
+- Full-vector reaction balance test.
+- Missing/unsupported input negative tests routed through the workflow.
+
+## Reference Artifacts
+- Normalized small `.inp` fixtures may be used.
+- Stored Abaqus CSV regression is reserved for step 14.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Workflow follows architecture boundaries.
+- `AnalysisState` owns mutable vectors.
+- Results use documented step/frame/field structure.
+
+## Handoff Requirements
+- Record end-to-end workflow readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not bypass validators to make a model solve.
@@ -0,0 +1,61 @@
+# Sprint Contract: Stored Reference Regression
+
+## Objective
+Run automated stored-reference displacement regression against accepted Phase 1-compatible S4 cases, starting with the `quad_02` compatibility path chosen in step 1.
+
+## Required Reading
+- /AGENTS.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/RESULTS_SCHEMA.md
+- /docs/MITC4_FORMULATION.md
+- /references/
+
+## Scope
+- Wire accepted Phase 1-compatible reference inputs into automated tests.
+- Compare FESA `U` against `*_displacements.csv` using documented tolerances.
+- Keep original unsupported Abaqus files as provenance and negative/compatibility tests.
+- Record pass/fail comparison details.
+
+## Allowed Files
+- `references/`
+- `tests/`
+- `include/`
+- `src/` only for minimal fixes needed by reference regression
+- `docs/VERIFICATION_PLAN.md`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not require Abaqus execution.
+- Do not accept `S4R`, `Part/Assembly/Instance`, `*Density`, or `NLGEOM=YES` through the parser without a prior parser contract.
+- Do not mark Phase 1 complete with only one reference case unless `PLAN.md` records the remaining PRD gap.
+
+## Tests To Write First
+- Reference manifest or fixture discovery tests.
+- `quad_02` accepted derivative input regression test if normalized in step 1.
+- Original `quad_02.inp` unsupported-provenance test if parser scope still excludes `Part/Assembly/Instance`.
+- CSV displacement comparison test with absolute and relative tolerances.
+
+## Reference Artifacts
+- `references/quad_02.inp`
+- `references/quad_02_displacements.csv`
+- Any normalized Phase 1-compatible derivative files from step 1.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Regression uses stored artifacts only.
+- Original reference provenance is preserved.
+- Comparison is node-id-based and reports errors clearly.
+- Remaining PRD requirement for three stored references is recorded if not satisfied.
+
+## Handoff Requirements
+- Record reference pass/fail, tolerances, and residual risks in `PROGRESS.md`.
+- Update `PLAN.md` with additional reference cases still needed.
+
+## Do Not
+- Do not tune solver formulas to one CSV without element-level tests remaining green.
@@ -0,0 +1,65 @@
+# Sprint Contract: Phase 1 Evaluator Closeout
+
+## Objective
+Perform an independent Phase 1 evaluation against the rebaseline contracts, docs, tests, reference artifacts, and validation commands.
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/PRD.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/RESULTS_SCHEMA.md
+- /docs/MITC4_FORMULATION.md
+- /phases/1-linear-static-mitc4-rebaseline/index.json
+
+## Scope
+- Review all completed rebaseline steps.
+- Run validation.
+- Produce pass/fail findings.
+- Update phase status, `PLAN.md`, and `PROGRESS.md` with final Phase 1 state.
+
+## Allowed Files
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/index.json`
+- `phases/1-linear-static-mitc4-rebaseline/index.json`
+- Optional evaluator feedback artifact under `phases/1-linear-static-mitc4-rebaseline/`
+
+## Explicit Non-Goals
+- Do not implement missing solver behavior during evaluation.
+- Do not approve unresolved reference gaps silently.
+- Do not mark old superseded phase steps as evidence for new MITC4 formulation compliance unless they were revalidated.
+
+## Tests To Write First
+- None. This is an evaluator sprint.
+
+## Reference Artifacts
+- All accepted Phase 1 reference artifacts under `references/`.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- All CRITICAL `AGENTS.md` rules are satisfied.
+- TDD expectations are met for implementation steps.
+- MITC4 implementation follows `docs/MITC4_FORMULATION.md`.
+- Parser has not silently expanded unsupported Abaqus features.
+- `RF` is recovered from full vectors.
+- At least one stored displacement reference regression passes, and remaining PRD reference gaps are explicit.
+- `PLAN.md` and `PROGRESS.md` are synchronized.
+
+## Handoff Requirements
+- If passed, mark the rebaseline phase complete and move remaining Phase 2 or reference tasks to `PLAN.md`.
+- If failed, write a concise feedback artifact with required fixes and commands to rerun.
+
+## Do Not
+- Do not self-approve implementation without evidence from tests and reference comparisons.
@@ -0,0 +1,58 @@
+# Sprint Contract: Core Harness Guardrails
+
+## Objective
+Refresh the build, validation, core numeric aliases, DOF enum, and diagnostic guardrails so later MITC4 work has stable test foundations.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/HARNESS_ENGINEERING.md
+- /scripts/validate_workspace.py
+
+## Scope
+- Preserve or repair CMake/CTest validation.
+- Verify `double` and signed int64 aliases are centralized.
+- Verify `UX`, `UY`, `UZ`, `RX`, `RY`, `RZ` mapping to Abaqus DOF `1..6`.
+- Improve diagnostics only where needed for later steps.
+
+## Allowed Files
+- `CMakeLists.txt`
+- `include/`
+- `src/`
+- `tests/`
+- `scripts/validate_workspace.py`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not implement parser features.
+- Do not implement MITC4 stiffness.
+- Do not introduce MKL, TBB, or HDF5 APIs into solver core.
+
+## Tests To Write First
+- DOF enum and Abaqus DOF number mapping tests.
+- Numeric alias compile-time or runtime tests for `double` and int64 paths.
+- Validation script smoke test through `python scripts/validate_workspace.py`.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Core aliases and DOF mapping are not duplicated across modules.
+- Diagnostics include enough context for later parser, model, and singular errors.
+- Validation remains a real build plus test command.
+
+## Handoff Requirements
+- Record changed guardrails and test coverage in `PROGRESS.md`.
+- Leave future parser/MITC4 tasks in later step files.
+
+## Do Not
+- Do not weaken validation to make tests pass.
+- Do not add external library dependencies in this step.
@@ -0,0 +1,58 @@
+# Sprint Contract: Parser Domain Subset
+
+## Objective
+Revalidate and repair the Phase 1 Abaqus parser and `Domain` model against the documented subset while preserving strict rejection of unsupported reference features.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/MITC4_FORMULATION.md
+
+## Scope
+- Parse Phase 1 keywords into immutable `Domain` objects.
+- Preserve node, element, set, material, shell section, boundary, load, and step definitions.
+- Reject `S4R`, `Part/Assembly/Instance`, `*Include`, `NLGEOM=YES`, nonzero prescribed displacement, and unsupported material/section modes.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `docs/ABAQUS_INPUT_SUBSET.md` only for clarifying parser contract
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not implement analysis or assembly.
+- Do not add `Part/Assembly/Instance` support because `quad_02` contains it.
+- Do not normalize reference files in parser code.
+
+## Tests To Write First
+- Parser acceptance tests for every Phase 1 keyword.
+- Generated and explicit `*Nset` and `*Elset` tests.
+- Unsupported feature rejection tests for `S4R`, `Part`, `Assembly`, `Instance`, `*Density`, and `NLGEOM=YES`.
+- Line-numbered diagnostic tests for malformed numeric and DOF fields.
+
+## Reference Artifacts
+- `references/quad_01.inp` as unsupported provenance.
+- `references/quad_02.inp` as unsupported original provenance until normalized or parser scope changes.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Parser behavior matches `docs/ABAQUS_INPUT_SUBSET.md`.
+- `TYPE=S4` maps to internal MITC4.
+- Unsupported stored references are not silently accepted.
+- Domain objects do not own equation numbers.
+
+## Handoff Requirements
+- Update `PROGRESS.md` with parser status.
+- Update `PLAN.md` for unresolved reference compatibility work.
+
+## Do Not
+- Do not broaden the parser subset without ADR and doc updates.
@@ -0,0 +1,56 @@
+# Sprint Contract: Validation Singular Diagnostics
+
+## Objective
+Strengthen domain and analysis-model validation so invalid inputs and singular-prone models fail before or during solve with actionable diagnostics.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/VERIFICATION_PLAN.md
+
+## Scope
+- Validate missing nodes, properties, materials, sets, boundary targets, load targets, active elements, and non-positive thickness.
+- Add singular-prone diagnostics for no free DOFs, untouched free DOFs, missing loads where expected, and unconstrained drilling/rotational risks.
+- Keep mesh quality diagnostics out of Phase 1.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not implement mesh quality metrics such as aspect ratio, skew, or warpage.
+- Do not solve the global system in this step.
+- Do not hide singular checks in element kernels.
+
+## Tests To Write First
+- Missing node/property/material diagnostics.
+- Missing set used by shell section, boundary, or load.
+- No active elements.
+- No free DOFs.
+- Free DOFs untouched by any active element connectivity.
+- Rotational/drilling weak-constraint diagnostic smoke test.
+
+## Reference Artifacts
+- Negative inline test inputs may be used.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Diagnostics include node id, element id, property id, material id, set name, DOF component, and source line where available.
+- Mesh quality remains explicitly deferred.
+- Validation does not mutate `Domain`.
+
+## Handoff Requirements
+- Record validation coverage in `PROGRESS.md`.
+- Note any remaining singular-diagnostic gaps in `PLAN.md`.
+
+## Do Not
+- Do not classify poor element shape as a Phase 1 mesh quality failure.
@@ -0,0 +1,57 @@
+# Sprint Contract: Dof Manager Reaction Foundation
+
+## Objective
+Rebuild or verify the six-DOF `DofManager`, constrained/free mapping, equation numbering, sparse-pattern inputs, and full-vector reconstruction needed for reaction recovery.
+
+## Required Reading
+- /AGENTS.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/RESULTS_SCHEMA.md
+
+## Scope
+- Manage active six-DOF shell nodes.
+- Apply fixed constraints by constrained DOF elimination.
+- Own equation numbering and sparse connectivity inputs.
+- Reconstruct full vectors in original global DOF order.
+- Provide data needed for `RF = K_full * U_full - F_full`.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not assemble MITC4 stiffness.
+- Do not store equation ids in `Node` or `Element`.
+- Do not compute `RF` from reduced vectors only.
+
+## Tests To Write First
+- DOF activation and Abaqus component order.
+- Constrained/free partition tests.
+- Equation numbering stability with noncontiguous node ids.
+- Full/reduced vector reconstruction tests.
+- Sparse-pattern connectivity input tests.
+- Full-vector reaction formula unit test with a small known matrix.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- `DofManager` owns all equation numbering.
+- Full-space order is deterministic and matches `UX,UY,UZ,RX,RY,RZ`.
+- Reaction foundation preserves constrained DOF information.
+
+## Handoff Requirements
+- Record DOF and reaction foundation status in `PROGRESS.md`.
+
+## Do Not
+- Do not bypass `DofManager` from elements or analysis code.
@@ -0,0 +1,57 @@
+# Sprint Contract: Results Comparator Foundation
+
+## Objective
+Rebuild or verify the minimum Phase 1 results model and Abaqus displacement CSV comparator before using stored reference regressions.
+
+## Required Reading
+- /AGENTS.md
+- /docs/RESULTS_SCHEMA.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/NUMERICAL_CONVENTIONS.md
+
+## Scope
+- Store minimum result model data for nodes, elements, `U`, and `RF`.
+- Preserve step/frame/field structure even if HDF5 writing is deferred.
+- Load Abaqus `*_displacements.csv` by node id and component label.
+- Compare using absolute and relative tolerances.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `docs/RESULTS_SCHEMA.md` only for clarifying schema text
+- `docs/VERIFICATION_PLAN.md` only for clarifying tolerance/reference text
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not make `S`, `E`, or `SF` mandatory.
+- Do not require Abaqus execution.
+- Do not rely on CSV row order.
+
+## Tests To Write First
+- `U` and `RF` field component labels and basis tests.
+- CSV required-header tests.
+- Duplicate/missing/non-numeric node row tests.
+- Node-id-based comparison tests with absolute and relative tolerance paths.
+- Result frame metadata tests for Phase 1 linear static frame 0.
+
+## Reference Artifacts
+- `references/quad_02_displacements.csv`
+- `references/quad_01_displacements.csv`
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Result component order matches docs.
+- Comparator maps Abaqus columns to FESA `U` labels exactly.
+- `RF` exists as a result field even if Abaqus RF CSV is unavailable.
+
+## Handoff Requirements
+- Record comparator readiness and remaining RF artifact decision in `PROGRESS.md` and `PLAN.md`.
+
+## Do Not
+- Do not add undocumented CSV formats.
@@ -0,0 +1,55 @@
+# Sprint Contract: MITC4 Geometry Directors
+
+## Objective
+Implement or rebuild MITC4 shape functions, natural-coordinate node order, element-center director policy, local director axes, and integration-point local bases.
+
+## Required Reading
+- /AGENTS.md
+- /docs/MITC4_FORMULATION.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ADR.md
+
+## Scope
+- Define `N1..N4` and derivatives for FESA natural coordinates.
+- Define tying points `A`, `B`, `C`, and `D`.
+- Build element-center director `Vn` from midsurface geometry.
+- Build nodal `V1`, `V2`, `Vn` and integration local Cartesian basis.
+- Add invalid/singular element diagnostics for near-zero normal, basis, Jacobian, and thickness.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not compute stiffness.
+- Do not add Abaqus `*Orientation` or nodal normal parsing.
+- Do not add mesh quality diagnostics.
+
+## Tests To Write First
+- Shape function partition-of-unity and derivative tests.
+- Node order and tying-point coordinate tests.
+- Flat element normal and right-handed basis tests.
+- Fallback axis tests when `EY x Vn` is near zero.
+- Invalid geometry diagnostic tests.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Geometry matches `docs/MITC4_FORMULATION.md`.
+- The old averaged-edge basis is not used as the binding formulation.
+- No stress/strain or stiffness logic is slipped into this step.
+
+## Handoff Requirements
+- Record MITC4 geometry readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not silently support strongly warped/nodal-director behavior beyond the documented Phase 1 policy.
@@ -0,0 +1,54 @@
+# Sprint Contract: MITC4 Covariant Strain Tying
+
+## Objective
+Implement or rebuild the degenerated-continuum displacement interpolation, direct covariant strain rows, and MITC transverse shear tying interpolation.
+
+## Required Reading
+- /AGENTS.md
+- /docs/MITC4_FORMULATION.md
+- /docs/NUMERICAL_CONVENTIONS.md
+
+## Scope
+- Implement five-DOF local displacement interpolation.
+- Transform global rotations to local `alpha`, `beta`, and `gamma`.
+- Compute direct covariant strain rows in documented internal strain order.
+- Replace `eps_13` and `eps_23` with midside MITC tying interpolation.
+- Add finite-difference tests for strain rows.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not integrate stiffness.
+- Do not add material transform.
+- Do not compute MITC shear from Cartesian `gamma_xz` and `gamma_yz` first.
+
+## Tests To Write First
+- Local rotation transform tests for `alpha`, `beta`, `gamma`.
+- Displacement interpolation tests at midsurface and through-thickness points.
+- Direct covariant strain finite-difference tests.
+- Tying-row tests at `A`, `B`, `C`, and `D`.
+- Gauss-point MITC shear interpolation tests proving rows come from tying rows.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- Strain vector ordering is documented or explicitly permuted.
+- `gamma` does not contribute to physical continuum strain.
+- FESA sign convention for `A/C/B/D` is tested.
+
+## Handoff Requirements
+- Record strain/tying readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not reintroduce direct Gauss-point transverse shear for MITC rows.
@@ -0,0 +1,54 @@
+# Sprint Contract: MITC4 Material Integration
+
+## Objective
+Implement or rebuild local plane-stress material behavior, shear correction, material transformation, and `2 x 2 x 2` Gauss integration scaffolding.
+
+## Required Reading
+- /AGENTS.md
+- /docs/MITC4_FORMULATION.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ARCHITECTURE.md
+
+## Scope
+- Implement isotropic linear elastic shell material matrix with `sigma_33 = 0` and `kappa = 5/6`.
+- Define material/strain ordering tests.
+- Implement or verify convected-to-local material transformation for Phase 1 cases.
+- Add `2 x 2 x 2` integration point and weight infrastructure.
+
+## Allowed Files
+- `include/`
+- `src/`
+- `tests/`
+- `PLAN.md`
+- `PROGRESS.md`
+
+## Explicit Non-Goals
+- Do not add composite sections.
+- Do not add stress/strain output recovery as mandatory output.
+- Do not switch to analytic thickness integration without equivalence tests and doc update.
+
+## Tests To Write First
+- Isotropic matrix value tests for known `E`, `nu`, and `kappa`.
+- Shear row ordering tests.
+- Integration point count and weights tests.
+- Flat element material transform identity/equivalence tests.
+- Invalid material/thickness diagnostic tests if not covered earlier.
+
+## Reference Artifacts
+- None.
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- `2 x 2 x 2` integration is the active baseline.
+- Material transform behavior is tested.
+- No reduced integration or hourglass logic is introduced.
+
+## Handoff Requirements
+- Record material and integration readiness in `PROGRESS.md`.
+
+## Do Not
+- Do not make S4R assumptions in material or integration code.