agent instructions setup

README.md

@@ -1,11 +1,12 @@
 # Just.PreciseMath
 
-**WIP — initial library implementation and one smoke test; numerical correctness is not yet validated.**
+Extended-precision floating-point arithmetic for .NET using double-double
+representations: a high/low pair of `double` values. The goal is to retain more
+precision than a single `double` while using a fixed-size representation,
+rather than arbitrary-precision arithmetic.
 
-A .NET 10 library being developed for extended-precision floating-point arithmetic
-using double-double representations (a high/low pair of `double` values), with
-common mathematical functions. This is fixed extended precision, not arbitrary
-precision; accuracy guarantees and the public API are not settled.
+> **Work in progress.** The public API is incomplete and may change. Numerical
+> accuracy has not been validated, and the library is not ready for production use.
 
 ## Planned scope
 
@@ -13,64 +14,35 @@ precision; accuracy guarantees and the public API are not settled.
 - Common functions including `Abs`, `Sqrt`, `Pow`, `Exp`, and `Log`.
 - Correctness tests against higher-precision references and performance benchmarks.
 
-The [consolidated legacy review](review-legacy/Review-Revisited-DoubleDouble.md)
-is the starting point. Priorities are normalization and special-value contracts
-(NaN, infinities, signed zero), corrected constants and scalar subtraction,
-consistent comparisons, precision-preserving conversions/formatting, and
-range-safe arithmetic and transcendental functions, including cancellation and
-subnormal cases. The files in `review-legacy/` contain known defects: they are
-reference material only, are not compiled, and should not be used in production.
+These are development goals, not a list of currently supported features.
 
-## Layout
+## Build and test
 
-- `0-source/Just.PreciseMath/` — library and package metadata.
-- `1-tests/Just.PreciseMath.Tests/` — xUnit v3, Shouldly, and MTP-native Coverlet.
-- `2-benchmarks/Just.PreciseMath.Benchmarks/` — BenchmarkDotNet scaffold.
-- `review-legacy/` — original implementation and numerical reviews.
-
-## Development
-
-Use the .NET 10 SDK selected by `global.json` (10.0.1xx, latest installed patch).
-Shared settings enable nullable analysis, .NET 10 recommended analyzers, build-time
-code-style checks, and warnings as errors. `.editorconfig` retains advisory style
-preferences alongside explicitly enforced warning/error rules.
+Requires the .NET 10 SDK in the `10.0.1xx` feature band, as selected by `global.json`.
+Run from the repository root:
 
 ```sh
-dotnet restore Just.PreciseMath.slnx
+dotnet restore Just.PreciseMath.slnx --locked-mode
 dotnet build Just.PreciseMath.slnx -c Release --no-restore
-dotnet test --solution Just.PreciseMath.slnx -c Release --no-build
+dotnet test --solution Just.PreciseMath.slnx -c Release --no-build --minimum-expected-tests 1
 dotnet format Just.PreciseMath.slnx --verify-no-changes --no-restore
 ```
 
-Commit each project's `packages.lock.json` with dependency changes. CI caches
-NuGet packages using those lock files and always runs `dotnet restore --locked-mode`,
-including on cache hits. After intentional dependency updates, run
-`dotnet restore --force-evaluate` and review the updated lock files before committing.
-Gitea's runner cache must be reachable from the job container, with persistent
-storage if the runner itself is recreated. No build outputs are cached.
+Test results and coverage reports are available in the `test-results` artifact
+on CI workflow runs.
 
-The initial smoke test checks that `DoubleDouble.One` exposes high and low
-components of `1.0` and `0.0`. It exercises the test/coverage pipeline, not the
-numerical accuracy of the planned library.
+## Project structure
 
-CI collects TRX test results and Cobertura coverage for `Just.PreciseMath` only,
-excluding test dependencies, and requires at least one test. The `test-results`
-artifact contains TRX test results and timestamped Cobertura XML coverage reports,
-retained for three days.
-Open the workflow run in Gitea Actions and download that artifact. Upload is
-attempted even when tests fail; no badges or repository-write token are needed.
+- `0-source/Just.PreciseMath/`: library implementation.
+- `1-tests/Just.PreciseMath.Tests/`: unit tests.
+- `2-benchmarks/Just.PreciseMath.Benchmarks/`: reserved for performance benchmarks.
 
-To generate the same reports locally:
+## Contributing
 
-```sh
-dotnet test --solution Just.PreciseMath.slnx -c Release --no-build --minimum-expected-tests 1 --report-xunit-trx --coverlet --coverlet-output-format cobertura --coverlet-include "[Just.PreciseMath]*"
-```
+Follow `.editorconfig` and include regression tests with numerical changes.
+Explain the algorithm's assumptions, the source of reference values, and any
+error tolerances. Include updated `packages.lock.json` files with dependency changes.
 
-Reports are written under each test project's `bin/Release/net10.0/TestResults/`.
-The benchmark project deliberately builds as a library without source files;
-add an entry point and benchmark cases, then change `OutputType` to `Exe` and run
-it in Release without a debugger. No performance results exist yet.
+## License
 
-Package metadata uses the development version `0.1.0-dev`. Licensed under the
-[MIT License](LICENSE), included in the package.
-Do not publish this scaffold as a usable numerical library.
+Licensed under the [MIT License](LICENSE).