# 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.