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,73 @@
+# Step 0: build-test-harness
+
+## Sprint Contract
+
+### Objective
+Establish the C++ project skeleton, build system, test framework, and validation script integration required before solver code begins.
+
+### Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- /docs/PRD.md
+- /docs/ARCHITECTURE.md
+- /docs/ADR.md
+- /docs/VERIFICATION_PLAN.md
+
+### Scope
+- Choose the Phase 1 build/test path. CMake is recommended unless project constraints require another choice.
+- Add a minimal C++17 project skeleton with one smoke-test target.
+- Wire `scripts/validate_workspace.py` to run real configured checks.
+- Document the build-system decision in ADR if it changes or becomes explicit.
+
+### Allowed Files
+- `CMakeLists.txt` or the selected build-system files
+- `src/**`
+- `include/**`
+- `tests/**`
+- `scripts/validate_workspace.py`
+- `README.md`
+- `docs/ADR.md`
+- `PLAN.md`
+- `PROGRESS.md`
+- `phases/1-linear-static-mitc4/index.json`
+
+### Explicit Non-Goals
+- Do not implement solver, parser, MITC4, results, or reference-comparison behavior.
+- Do not introduce MKL, TBB, or HDF5 APIs into solver core during this setup step.
+- Do not mark readiness blockers R-004 through R-011 as solved unless this step actually resolves them.
+
+### Tests To Write First
+- A minimal C++ smoke test that fails before the test harness is connected and passes after the harness is wired.
+- A validation-script test or self-check proving `python scripts/validate_workspace.py` reports the configured build/test command status.
+
+### Reference Artifacts
+- None. This step does not use `references/*.inp` or `references/*_displacements.csv`.
+
+### Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+### Evaluator Checklist
+- The project builds with C++17 or newer.
+- The chosen test framework runs through the validation script.
+- `scripts/validate_workspace.py` no longer reports that no checks are configured.
+- The build-system decision is documented if new or changed.
+- No solver behavior was implemented.
+
+### Handoff Requirements
+- Update `PROGRESS.md` with changed files, validation output, and any build-system caveats.
+- Update `PLAN.md` only for changed future work or resolved blockers.
+- 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. Confirm the smoke test is executed by the validation script.
+3. Inspect the diff for accidental solver behavior or dependency leakage.
+
+## Do Not
+- Do not expand Phase 1 scope to make a build demo more impressive.
+- Do not commit generated build artifacts.