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,74 @@
+# Step 9: reference-displacement-comparator
+
+## Sprint Contract
+
+### Objective
+Implement the `references/*_displacements.csv` loader and comparator for FESA `U` output.
+
+### Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/NUMERICAL_CONVENTIONS.md
+- /docs/VERIFICATION_PLAN.md
+- /docs/RESULTS_SCHEMA.md
+- /references/README.md
+- /phases/1-linear-static-mitc4/step8.md
+
+### Scope
+- Load Abaqus displacement CSV files with columns `Node Label`, `U-U1`, `U-U2`, `U-U3`, `UR-UR1`, `UR-UR2`, `UR-UR3`.
+- Compare by node id, not row order.
+- Implement absolute and relative tolerance behavior with a documented default or configuration path.
+- Report missing columns, duplicate nodes, missing nodes, nonnumeric values, and tolerance failures.
+
+### Allowed Files
+- `include/**`
+- `src/**`
+- `tests/**`
+- `references/**` only for small test fixtures or documentation updates
+- `docs/VERIFICATION_PLAN.md` only for comparator tolerance clarification
+- `docs/RESULTS_SCHEMA.md` only for schema clarification
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4/index.json`
+
+### Explicit Non-Goals
+- Do not require Abaqus execution.
+- Do not treat `references/quad_01.inp` as Phase 1 supported input.
+- Do not compare RF here unless a `*_reactions.csv` contract is added.
+
+### Tests To Write First
+- CSV header validation tests.
+- Node-id matching and row-order independence tests.
+- Absolute/relative tolerance pass/fail tests.
+- Duplicate, missing, and malformed value diagnostics tests.
+- Format-only smoke test using `references/quad_01_displacements.csv` if stable enough for CI.
+
+### Reference Artifacts
+- Format-only: `references/quad_01_displacements.csv`.
+- Required later for solver regression: at least one Phase 1-compatible `TYPE=S4` input and matching displacement CSV.
+
+### Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+### Evaluator Checklist
+- Component mapping matches `docs/VERIFICATION_PLAN.md` and `docs/RESULTS_SCHEMA.md`.
+- Comparison is by node id and independent of row order.
+- Missing or malformed reference data fails with actionable diagnostics.
+- `quad_01` is not used to imply S4R or nonlinear support.
+
+### Handoff Requirements
+- Record comparator behavior, tolerance decision, and validation in `PROGRESS.md`.
+- Update `PLAN.md` if R-009 or reference artifact blockers change.
+- 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. Inspect comparator tests for tolerance and malformed CSV behavior.
+
+## Do Not
+- Do not silently skip reference nodes or components.