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.

2 files changed, 198 insertions, 0 deletions

diff --git a/docs/progmasoft-catch3.md b/docs/progmasoft-catch3.md
new file mode 100644
index 00000000..96989479
--- /dev/null
+++ b/docs/progmasoft-catch3.md
@@ -0,0 +1,131 @@
+# Progmasoft Catch3 additions
+
+Progmasoft Catch3 is a compatibility-preserving extension of Catch2, not a
+replacement runner. The upstream `Catch2` API, command-line behavior, include
+paths, and BSL-1.0 files remain the compatibility foundation. Progmasoft-owned
+headers use the `Progmasoft/Catch3` include tree and `Progmasoft::Catch3`
+namespace.
+
+## Property testing
+
+`<Progmasoft/Catch3.hpp>` is the umbrella header. It brings in Catch2's
+`catch_all.hpp` as well as the Progmasoft extensions, so it is convenient but
+increases compile time. Include individual headers when a translation unit only
+needs a narrow part of the API.
+
+```cpp
+#include <Progmasoft/Catch3.hpp>
+
+TEST_CASE("integer values stay in their requested domain", "[property]") {
+    CATCH3_CHECK_PROPERTY(
+        Progmasoft::Catch3::Integer<int>(1, 100),
+        [](int value) { return value > 0; },
+        Progmasoft::Catch3::PropertyOptions{
+            .Trials = 250,
+            .Seed = 0xC0FFEE,
+            .MaxShrinkSteps = 200});
+}
+```
+
+The current property API is split into these headers:
+
+- `<Progmasoft/Catch3/Random.hpp>`: portable SplitMix64 sequence, unbiased
+  bounded sampling, inclusive integer ranges, and per-trial seed derivation.
+- `<Progmasoft/Catch3/Generator.hpp>`: user-defined generation/shrinking pair.
+- `<Progmasoft/Catch3/Generators/Integer.hpp>` and `Boolean.hpp`: built-in
+  strategies with deterministic shrink candidates.
+- `<Progmasoft/Catch3/Property.hpp>`: trial execution and structured results.
+- `<Progmasoft/Catch3/Assertions.hpp>`: `CATCH3_CHECK_PROPERTY`, which reports
+  the failing trial, replay seed, reason, and minimized counterexample through
+  Catch2's normal assertion/reporting path.
+
+`PropertyOptions::Seed` is a stable root seed. Each trial receives a seed derived
+from the root and its zero-based trial index, so the reported replay seed can be
+used to reproduce that trial independently. The default generator is also stable
+across standard-library implementations; it does not rely on the implementation-
+defined output sequence of `std::uniform_int_distribution`.
+
+Shrinking is deterministic and greedy: candidates are tested in the order
+provided by the generator, and the first still-failing candidate is selected.
+`MaxShrinkSteps` bounds predicate evaluations during minimization. The result is
+therefore a useful locally minimized counterexample, not a claim of a globally
+minimal value. A false predicate or an exception from the predicate fails the
+property. Exceptions from generation or shrinking are reported as execution
+errors, distinct from an ordinary failing property.
+
+The API currently accepts one generated value per property. Tuple strategies,
+state-machine commands, parallel trials, and adaptive shrinking are deliberately
+not implied by this first module; they need their own deterministic contracts and
+tests before being added.
+
+## Build and integration
+
+The CMake build exposes `Progmasoft::Catch3`, a C++20 interface target linked to
+`Catch2::Catch2`. The existing Catch2 target retains its C++14 baseline. After
+installation, consumers can use:
+
+```cmake
+find_package(Catch2 3.16 CONFIG REQUIRED)
+find_package(ProgmasoftCatch3 3.16 CONFIG REQUIRED)
+target_link_libraries(MyTests PRIVATE Progmasoft::Catch3 Catch2::Catch2WithMain)
+```
+
+The Bazel target is `//src/Progmasoft:catch3`; its tests are
+`//tests/Progmasoft:property_tests`. The compatibility project continues to
+build with Catch2's upstream build and test structure. Bazel is the primary
+build path; CMake, Meson, Xmake, and Premake are also maintained as alternate
+ways to build the same engine and property tests. Their root files are
+`CMakeLists.txt`, `meson.build`, `xmake.lua`, and `premake5.lua`. Xmake and
+Premake materialize Catch2's default generated configuration header from the
+checked-in upstream template. Meson 1.1.0 or newer is required for the Clang-CL
+C++20 test target.
+
+For project history, compatibility intent, license split, and current feature
+limits, read [Why Progmasoft Catch3?](why-catch3.md).
+
+## Build quick start
+
+Bazel is the primary build path:
+
+```sh
+bazel test //tests/Progmasoft:property_tests
+```
+
+The alternate project builds exercise the same property suite:
+
+```sh
+# CMake
+cmake -S . -B build/cmake -DCATCH_DEVELOPMENT_BUILD=ON -DCATCH_BUILD_TESTING=ON
+cmake --build build/cmake --target ProgmasoftSelfTest
+ctest --test-dir build/cmake -R Progmasoft --output-on-failure
+
+# Xmake
+xmake build ProgmasoftPropertyTests
+xmake run ProgmasoftPropertyTests
+
+# Meson (Windows PowerShell; requires the Visual C++ SDK/CRT)
+$env:CC = 'clang-cl'; $env:CXX = 'clang-cl'
+meson setup build/meson --vsenv -Dtests=true -Dinstall=false
+meson compile -C build/meson
+meson test -C build/meson --print-errorlogs
+
+# Premake (choose an action supported by the host)
+premake5 vs2022
+```
+
+Premake generates projects rather than compiling directly; build the generated
+solution with the corresponding host toolchain. On macOS, use
+`premake5 gmake`, then build the generated makefiles with `make`. Meson users on
+macOS can select Apple Clang with `CC=clang CXX=clang++` before configuration.
+
+## Compatibility and licensing boundary
+
+Do not rename or rewrite Catch2 headers, `Catch` symbols, macros, runner options,
+or upstream coding style as part of this extension. New functionality belongs
+in separately licensed Progmasoft headers and uses Progmasoft's PascalCase C++
+types/functions and project naming conventions. Catch2-originated source files
+remain under BSL-1.0; Progmasoft-authored source files carry the MPL-2.0 plus
+Progmasoft linking-exception SPDX expression shown in their headers. The two
+areas are not relicensed as a whole. Any proposed upstream PR must be prepared
+under Catch2's contribution rules as a separate contribution, rather than
+reusing a source file whose license header says otherwise.
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.