docs: add phase 1 sprint contracts

2026-05-01 02:40:19 +09:00
parent e99b5b8eff
commit 10f1436e0f
20 changed files with 1272 additions and 2 deletions
@@ -0,0 +1,69 @@
+# Step 5: domain-validation-diagnostics
+
+## Sprint Contract
+
+### Objective
+Implement Domain validation and singular-prone pre-solve diagnostics required before DOF and solver work.
+
+### Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/ABAQUS_INPUT_SUBSET.md
+- /docs/VERIFICATION_PLAN.md
+- /phases/1-linear-static-mitc4/step4.md
+
+### Scope
+- Validate node, element, set, material, property, load, boundary, and step references.
+- Add singular-prone diagnostics for no active elements, no material/property, no boundary constraints, untouched free DOFs when detectable, and invalid active step data.
+- Keep diagnostics actionable and source-linked where parser information is available.
+
+### Allowed Files
+- `include/**`
+- `src/**`
+- `tests/**`
+- `docs/VERIFICATION_PLAN.md` only for clarification of diagnostic test expectations
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4/index.json`
+
+### Explicit Non-Goals
+- Do not implement DofManager, assembly, or solver singularity handling in this step.
+- Do not add mesh quality diagnostics; Phase 1 excludes them.
+- Do not accept unsupported parser features to make validation easier.
+
+### Tests To Write First
+- Validation tests for missing nodes, missing sets, missing materials, missing shell sections, invalid element connectivity, invalid loads, and invalid boundary references.
+- Singular-prone tests for no active elements, unconstrained models, and untouched free DOF candidates where detectable without assembly.
+- Diagnostic payload tests for code, severity, message, and source/model context.
+
+### Reference Artifacts
+- None.
+
+### Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+### Evaluator Checklist
+- Diagnostics align with `docs/NUMERICAL_CONVENTIONS.md` and `docs/VERIFICATION_PLAN.md`.
+- Validation is separate from parsing and analysis execution.
+- Mesh quality checks were not introduced.
+- Tests cover failure modes, not only valid models.
+
+### Handoff Requirements
+- Record validation coverage and command results in `PROGRESS.md`.
+- Update `PLAN.md` if singular diagnostics require later solver support.
+- Update the matching phase index entry: use `completed` with a one-line `summary`, or `blocked` with `blocked_reason`, or `error` with `error_message`.
+
+## Verification
+1. Run the acceptance command.
+2. Review negative tests for clear diagnostics and no mesh-quality drift.
+
+## Do Not
+- Do not defer singular diagnostics entirely to the linear solver.