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,68 @@
+# Step 1: core-types-diagnostics
+
+## Sprint Contract
+
+### Objective
+Add core numeric/id types, shell DOF enumeration, diagnostics primitives, and error-result conventions used by later layers.
+
+### 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
+- /phases/1-linear-static-mitc4/step0.md
+
+### Scope
+- Define int64-based ids, indices, and equation-number types.
+- Define `double` as the default scalar precision.
+- Define the six shell DOFs in the documented order: `UX`, `UY`, `UZ`, `RX`, `RY`, `RZ`.
+- Add diagnostics/result primitives with enough context for parser, validation, and solver errors.
+
+### Allowed Files
+- `include/**`
+- `src/**`
+- `tests/**`
+- `docs/ADR.md`
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4/index.json`
+
+### Explicit Non-Goals
+- Do not add Domain, parser, DofManager, sparse matrix, or MITC4 element behavior.
+- Do not use 32-bit ids, equation numbers, or sparse indices.
+- Do not encode global equation ids inside node or element data structures.
+
+### Tests To Write First
+- Unit tests for id/index/equation type sizes and signedness expectations.
+- Unit tests for DOF ordering, component labels, and stable integer mapping.
+- Unit tests for diagnostic severity, code, message, and source-location payloads.
+
+### Reference Artifacts
+- None.
+
+### Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+### Evaluator Checklist
+- Core types are reusable without depending on parser, analysis, MKL, TBB, or HDF5.
+- DOF labels and order match `docs/NUMERICAL_CONVENTIONS.md`.
+- Diagnostics can carry actionable context for unsupported input and singular systems.
+- Tests were added before behavior and pass through validation.
+
+### Handoff Requirements
+- Record completed work and validation in `PROGRESS.md`.
+- Keep `PLAN.md` focused on future blockers only.
+- 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 tests for explicit int64 and DOF-order assertions.
+
+## Do Not
+- Do not infer future element or solver APIs beyond what this contract requires.