Add Progmasoft Catch3 property testing and build support0.1.0

Introduce deterministic property execution, built-in generators, shrinking, replayable seeds, and a separate Progmasoft-owned header API while preserving Catch2 compatibility targets and the C++14 engine baseline.

Add Bazel, Meson, Xmake, and Premake integration and tests alongside the existing CMake build. Replace Linux-only workflow coverage with Windows and macOS jobs and document the Catch2/Catch3 distinction.

1 files changed, 67 insertions, 0 deletions

diff --git a/docs/why-catch3.md b/docs/why-catch3.md
new file mode 100644
index 00000000..0b62402f
--- /dev/null
+++ b/docs/why-catch3.md
@@ -0,0 +1,67 @@
+# Why Progmasoft Catch3?
+
+Progmasoft Catch3 is an independently maintained continuation built on the
+Catch2 v3 codebase. It exists to preserve Catch2's practical testing model while
+giving Progmasoft room to add capabilities and APIs under a clear ownership,
+namespace, build-target, and licensing boundary.
+
+The name does **not** mean that this is an official Catch2 v3 release, a new
+upstream version, or a project endorsed by Catch2's maintainers. The current
+compatibility engine is based on Catch2's 3.16.0 development line. The project
+is still early-stage and does not yet replace or independently reimplement the
+Catch2 runner.
+
+## What is different today?
+
+| Area | Catch2 compatibility engine | Progmasoft Catch3 additions |
+| --- | --- | --- |
+| Test execution | Catch2's existing runner, reporters, command-line interface, and test registration | `CATCH3_CHECK_PROPERTY` reports property outcomes through Catch2's assertion path |
+| Public include path | Existing `catch2/...` headers | `Progmasoft/Catch3.hpp` and focused `Progmasoft/Catch3/...` headers |
+| C++ baseline | Existing Catch2 target remains at C++14 | The added property API requires C++20 |
+| Randomness | Catch2's existing behavior is unchanged | A specified SplitMix64 sequence provides deterministic trial seeds and unbiased bounded integer sampling |
+| Generated values | No change to existing Catch2 generators | Initial integer/boolean strategies, custom generator callbacks, and bounded greedy shrinking |
+| Build identity | Existing `Catch2` target and APIs remain available | Separate `Progmasoft::Catch3` CMake target and `//src/Progmasoft:catch3` Bazel target |
+| Source terms | Catch2-originated source retains its upstream BSL-1.0 terms | Progmasoft-authored additions state their own SPDX license in each file |
+
+The current property runner handles one generated value per property. Shrinking
+is deterministic and bounded, but greedy rather than globally minimal. There is
+not yet built-in support for state-machine properties, generated tuples,
+discard/classification policies, parallel execution, or a standalone Catch3
+runner. Those features are not implied by the initial API.
+
+## Compatibility policy
+
+Catch2's `Catch` namespace, established headers, macros, command-line behavior,
+reporters, and coding style remain the compatibility surface. Progmasoft
+features should be added under `Progmasoft::Catch3` and must not require users
+to rename existing Catch2 tests. The first compatibility goal is source-level
+continuity with the included Catch2 3.16.0 base; this is not a promise that every
+future Catch2 upstream change will be adopted unchanged or that all downstream
+projects have already been validated.
+
+The split also applies to implementation and packaging: Catch2 remains the
+engine dependency, while Progmasoft's header-only API is a separate target.
+Keep tests for the two areas independently identifiable so additions do not
+silently alter the upstream compatibility baseline.
+
+## Why a fork instead of a patch series?
+
+The initial additions need their own design and release cycle. Keeping them in a
+separate namespace and file tree lets the project prototype those APIs without
+presenting them as upstream Catch2 behavior. If a change is later proposed to
+Catch2 upstream, prepare it as a separate contribution under Catch2's current
+contribution and licensing requirements; do not assume Progmasoft-licensed
+files can be submitted unchanged.
+
+## Build-system support
+
+Bazel is the primary build and validation path. CMake, Meson, Xmake, and Premake
+are supported alternate project-generation/build paths over the same local sources.
+The CMake project preserves the upstream `Catch2` targets and adds
+`Progmasoft::Catch3`; the other build descriptions compile the same Catch2
+engine and the Progmasoft property-test executable. See the repository build
+instructions and each build file for tool-specific commands.
+
+Registry publication is a separate release step. It requires a versioned
+immutable source archive and successful validation and maintainer review for
+the `catch3` module name; a submission is not a guarantee of acceptance.