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 7: math-solver-adapters
+
+## Sprint Contract
+
+### Objective
+Implement vector, sparse matrix, and linear solver interfaces plus a deterministic test solver adapter while preserving future MKL/TBB adapter boundaries.
+
+### 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/step6.md
+
+### Scope
+- Add minimal vector and sparse matrix abstractions needed by assembly and linear static solving.
+- Add a linear solver interface with deterministic test implementation.
+- Keep MKL/TBB-specific code behind adapter boundaries if any placeholder is added.
+- Surface solver singularity diagnostics in a structured way.
+
+### Allowed Files
+- `include/**`
+- `src/**`
+- `tests/**`
+- `docs/ADR.md` if adapter decisions need clarification
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4/index.json`
+
+### Explicit Non-Goals
+- Do not require Intel oneAPI installation for Phase 1 unit tests.
+- Do not expose MKL, TBB, or HDF5 APIs in solver core headers.
+- Do not implement element assembly or analysis algorithms in this step.
+
+### Tests To Write First
+- Sparse pattern and insertion tests with int64 indices.
+- Deterministic small linear solve tests.
+- Singular solve diagnostic tests.
+- Adapter-boundary tests or compile checks showing core APIs do not include MKL/TBB headers.
+
+### Reference Artifacts
+- None.
+
+### Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+### Evaluator Checklist
+- Core math interfaces are dependency-clean.
+- Singular solver failures produce diagnostics, not crashes or silent NaNs.
+- Tests cover sparse storage, solve success, and solve failure.
+- Future MKL acceleration remains possible without changing solver core contracts.
+
+### Handoff Requirements
+- Record math interfaces, validation, and adapter caveats in `PROGRESS.md`.
+- Update `PLAN.md` if MKL/TBB integration becomes a future task.
+- 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 public headers for third-party API leakage.
+
+## Do Not
+- Do not optimize sparse storage before correctness and testability are established.