@cratis/pi 7.103.5 → 7.103.7

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -25,8 +25,8 @@ Sources:
 
 | Package | Purpose |
 | --- | --- |
-| `Cratis.Specifications.XUnit` | `Specification` base, lifecycle discovery, `ShouldXxx` assertions, optional shared lifecycle |
-| `Cratis.Specifications` | `Catch.Exception`, `SpecificationMethods` (dependency of the XUnit package) |
+| `Cratis.Specifications.XUnit.v3` | `Specification` base, lifecycle discovery, `ShouldXxx` assertions, shared lifecycle by default (house default; `.XUnit` is the xUnit v2 equivalent) |
+| `Cratis.Specifications` | `Catch.Exception`, `SpecificationMethods` (dependency of the XUnit packages) |
 | `Cratis.Arc.Testing` | `CommandScenario<TCommand>` preserves explicit principal/override/policy services; see application-scenarios |
 | `Cratis.Chronicle.Testing` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
 
@@ -100,10 +100,14 @@ resolved read-model key. See the ReactorScenario reference for diagnostics,
 exception capture and UTC occurrence-time defaults.
 
 Specification projects are named `<Source>.Specs`. Add a `PackageReference` to
-`Cratis.Specifications.XUnit`, not just `Cratis.Specifications`; the C#
-namespace stays `Cratis.Specifications`. The house runner is xUnit **2.x**
-not xUnit v3. Supported targets are net8.0/net9.0/net10.0;
-net48 was dropped (retain 3.x for that target).
+`Cratis.Specifications.XUnit.v3`, not just `Cratis.Specifications`; the C#
+namespace stays `Cratis.Specifications`. The house default is Specifications 5
+on xUnit v3 with `xunit.v3.mtp-off` and `<OutputType>Exe</OutputType>`, run as
+the built executable. 5.0 targets net10.0 only; net8.0/net9.0 projects stay on
+4.x and net48 on 3.x. A project that stays on xUnit v2 references
+`Cratis.Specifications.XUnit`. Read [running-specs.md](references/running-specs.md)
+for the project shape, the executable loop, filters, mixed solutions and the
+4.x → 5.0 checklist; the `run-tests` and `filter-syntax` skills own command choice.
 `Cratis.Specifications.NUnit` is an alternative with the same base pattern,
 `[Test]` instead of `[Fact]`, and **public** test methods.
 
@@ -199,15 +203,18 @@ public class when_<behavior> : Specification
 - Fields are `private` in a concrete specification and `protected` in a `given/`
   context, named `_camelCase`.
 - Any phase may be `async Task`. `void Destroy()` is optional teardown, after
-  each fact by default; once per eligible class with the shared lifecycle opt-in.
+  once per eligible class by default (shared lifecycle); after each fact in a
+  `[PerFactSpecificationLifecycle]` class.
 
-`Cratis.Specifications.XUnit` discovers `Establish`, `Because`, and `Destroy` by
+`Cratis.Specifications.XUnit.v3` discovers `Establish`, `Because`, and `Destroy` by
 convention — there are no attributes on them.
 
-Keep the stock per-fact lifecycle by default. Read
-[shared-lifecycle.md](references/shared-lifecycle.md) when deliberately opting
-into one instance and one Establish/Because execution per specification class.
-Facts must not mutate that shared context.
+The shared lifecycle is the default: one instance and one Establish/Because
+execution per specification class. Facts must not mutate that shared context;
+`CRSPEC0008` is an error when one does. Read
+[shared-lifecycle.md](references/shared-lifecycle.md) for eligibility, opting a
+class, assembly or project out with `[PerFactSpecificationLifecycle]`, and
+fixing `CRSPEC0008`.
 
 ## Step 4 — Extract a reusable context
 
@@ -297,7 +304,7 @@ between collaborators. That is where defects hide.
 Requires `Cratis.Specifications` 4.0.0 for the analyzers.
 
 CRSPEC0001–CRSPEC0007 ship as **warnings** in `Cratis.Specifications`, `.XUnit`,
-and `.NUnit`. A warnings-as-errors build enforces them: `should_` names,
+`.XUnit.v3` and `.NUnit`; `CRSPEC0008` is an error. A warnings-as-errors build enforces them: `should_` names,
 one specification per file (given contexts exempt), no facts on given contexts,
 test attributes on `should_` methods, no explicit base lifecycle calls, public
 specification classes, and no `Because` on given contexts. See

package/package/corpus/skills/cratis-specifications-csharp/references/running-specs.md

@@ -0,0 +1,90 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Running specifications and migrating to 5.0
+
+Requires `Cratis.Specifications.XUnit.v3` 5.0 on `net10.0`. Check the
+`PackageReference` versions in the specification project; 4.x projects follow the
+checklist below before the executable loop applies.
+
+Sources: [Running specifications fast](https://github.com/Cratis/Specifications/blob/main/Documentation/running-fast.md),
+[The native runner](https://github.com/Cratis/Specifications/blob/main/Documentation/runner.md) and
+[Upgrading to 5.0](https://github.com/Cratis/Specifications/blob/main/Documentation/upgrading-5.0.md).
+
+## Project shape
+
+```xml
+<PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <OutputType>Exe</OutputType>
+</PropertyGroup>
+<ItemGroup>
+    <PackageReference Include="Cratis.Specifications.XUnit.v3" />
+    <PackageReference Include="xunit.v3.mtp-off" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+</ItemGroup>
+```
+
+Versions live in `Directory.Packages.props`. Keep `Cratis.Specifications` and the
+adapter package on the same version. The Cratis AI repository's `Source/Cratis.AI.Specs`
+is a worked example, including the CI step that runs the built executable.
+
+## Local loop
+
+An xUnit v3 suite costs about 4.5 times more CPU through `dotnet test` than as the
+built executable (indicative, from the upstream benchmark). Restore and build once,
+then run the executable:
+
+```bash
+dotnet restore Source/MyProject.Specs
+dotnet build Source/MyProject.Specs --configuration Release --no-restore
+./Source/MyProject.Specs/bin/Release/net10.0/MyProject.Specs
+```
+
+Without an apphost, run `dotnet <path>/MyProject.Specs.dll`. `dotnet run --no-build`
+also works but still starts MSBuild to resolve the project, so prefer the executable
+for repeated runs. A pass is exit code 0 with the reported total equal to the
+passed count.
+
+Where a solution mixes Microsoft.Testing.Platform and VSTest projects, run each
+project on its own; `dotnet test` on the whole solution does not work there.
+
+## Filters
+
+The executable accepts the filters of the xUnit v3 runner flavor the project
+references. Check the flavor with `<executable> -h`; the `run-tests` skill owns
+the command choice and `filter-syntax` owns the expression syntax.
+
+| Project references | Filter flags |
+| --- | --- |
+| `xunit.v3.mtp-off` (house default) | `-class`, `-method`, `-namespace`, `-trait`, or one `-filter "<query>"`; do not mix the three kinds |
+| MTP-enabled `xunit.v3` | `--filter-class`, `--filter-method`, `--filter-trait`, or one `--filter-query` |
+| `Cratis.Specifications.Runner` (experimental native runner) | `--treenode-filter '/*/*/when_registering/*'` or `--filter-uid <uid>` |
+
+Do not use `dotnet test --filter` against an MTP executable. See the
+[`run-tests`](../../run-tests/SKILL.md) and [`filter-syntax`](../../filter-syntax/SKILL.md)
+skills for the exact command per platform.
+
+## Migrate from 4.x to 5.0
+
+Follow the upstream [upgrade guide](https://github.com/Cratis/Specifications/blob/main/Documentation/upgrading-5.0.md)
+and record the spec count and outcomes first.
+
+1. Record the baseline: total, passed, failed and skipped counts, and the list of
+   discovered classes and methods, from the unmodified branch.
+2. Target `net10.0` in every specification project; projects that must stay on
+   net8.0/net9.0 stay on 4.x.
+3. Move `Cratis.Specifications` and the adapter package to the same 5.0 version. For
+   xUnit v3 switch to `Cratis.Specifications.XUnit.v3`, `xunit.v3.mtp-off` and
+   `<OutputType>Exe</OutputType>`.
+4. Delete any `[assembly: Xunit.TestFramework(...)]` that registers Cratis
+   Specifications.
+5. Fix each `CRSPEC0008` error by moving the change into `Establish` or `Because`; use
+   `[PerFactSpecificationLifecycle]` only when the fact genuinely needs a fresh instance.
+6. Rebuild with warnings as errors and fix new nullable warnings.
+7. Run the executable and require the same total, the same passed count and the same
+   classes and methods as the baseline (display names may become more readable),
+   with no new skips. A different count means a spec was
+   lost or duplicated; investigate before continuing.
+8. Point CI at the built executable, and run mixed solutions project by project.

package/package/corpus/skills/cratis-specifications-csharp/references/shared-lifecycle.md

@@ -1,38 +1,70 @@
 <!-- Copyright (c) Cratis. All rights reserved. -->
 <!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
 
-# Optional shared xUnit lifecycle
+# Shared specification lifecycle
 
-Source: `Cratis.Specifications.XUnit`,
-`SpecificationTestFramework.cs`, `SpecificationTestClassRunner.cs`, and
-`Specification.cs`.
+Requires `Cratis.Specifications.XUnit.v3` or `.XUnit` 5.0. Before 5.0 the shared
+lifecycle was an opt-in on xUnit and `CRSPEC0008` was informational; check the package
+version before relying on either. NUnit, TUnit and the native runner always share the
+instance.
 
-Requires `Cratis.Specifications.XUnit` 4.1.0.
+Source: [Running specifications fast](https://github.com/Cratis/Specifications/blob/main/Documentation/running-fast.md)
+and [Upgrading to 5.0](https://github.com/Cratis/Specifications/blob/main/Documentation/upgrading-5.0.md).
 
-The house default remains stock xUnit
-per-fact execution.
+The shared lifecycle is the house default. Plain xUnit builds a new instance per fact,
+so `Establish` and `Because` would run once per fact; the shared lifecycle runs them
+once per class, which is what a specification means: one context, one action,
+several assertions. Construction, `Establish` and `Because` happen once, all facts share
+the instance, and `Destroy` runs once after the last fact, including when
+initialization failed. A throwing `Establish` or `Because` fails every fact in that
+class.
 
-## Opt in
+The package registers the test framework. Delete any hand-written
+`[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", ...)]`;
+a duplicate fails the build with `CS0579`.
 
-Add this assembly attribute to the specification project:
+## Eligibility
+
+A class is shared only when it derives from `Specification`, has a single public
+parameterless constructor (or only framework-managed fixture arguments), does not
+implement `IDisposable`, and has only plain facts. Theories, `ITestOutputHelper`
+constructors, custom `IAsyncLifetime` implementations, custom fact test cases and plain
+xUnit classes keep the per-fact lifecycle.
+
+`Specification.InitializeAsync()` is idempotent for a single instance. It does not make
+an ineligible class shared or cache instances across classes.
+
+## CRSPEC0008
+
+`CRSPEC0008` is an error by default: a `should_` fact that assigns to or increments an
+instance field or property of the specification, or calls `Add`, `AddRange`, `Remove`,
+`RemoveAt`, `Clear` or `Insert` on one, would make the result depend on fact order.
+Move the change into `Establish` or `Because`:
 
 ```csharp
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+public class when_registering : Specification
+{
+    List<string> _registered;
 
-[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", "Cratis.Specifications.XUnit")]
+    void Establish() => _registered = [];
+    void Because() => _registered.Add("first");
+
+    [Fact] void should_have_one_registration() => _registered.Count.ShouldEqual(1);
+}
 ```
 
-For eligible classes, construction, `Establish`, and `Because` happen once.
-All facts share the instance; `Destroy` runs once after the last fact, including
-when initialization failed. A throwing `Establish` or `Because` fails every fact
-in that class. Facts must only assert, never mutate shared context.
+Do not lower the severity to pass the gate. When the repository must lower it, set it in
+`.editorconfig` with `dotnet_diagnostic.CRSPEC0008.severity = warning`.
+
+## Keep per-fact execution
+
+Use the narrowest scope; the reason is a fact that genuinely needs a fresh instance.
 
-A class is eligible only when it derives from `Specification`, has a single
-public parameterless constructor, does not implement `IDisposable`, and has only
-plain facts. Theories, custom fact test cases, fixture/output-helper constructors,
-and plain xUnit classes keep the stock per-fact lifecycle. This is not xUnit v3
-support; the package uses xUnit 2.x.
+| Scope | How |
+| --- | --- |
+| One class | `[PerFactSpecificationLifecycle]` on the class |
+| The assembly | `[assembly: PerFactSpecificationLifecycle]` |
+| The project | `<CratisSpecificationsSharedLifecycle>false</CratisSpecificationsSharedLifecycle>` |
 
-`Specification.InitializeAsync()` is idempotent for a single instance. It does
-not make an ineligible class shared or cache instances across classes.
+Read [running-specs.md](./running-specs.md) for the executable loop and the 4.x → 5.0
+checklist.

package/package/corpus/skills/cratis-specifications-csharp/verification.json

@@ -3,9 +3,11 @@
   "input": "Set up a C# specification project and choose its lifecycle.",
   "fixtures": [],
   "assertions": [
-    { "kind": "skill-contains", "value": "Cratis.Specifications.XUnit" },
-    { "kind": "skill-contains", "value": "xUnit **2.x**" },
-    { "kind": "skill-contains", "value": "stock per-fact lifecycle by default" },
+    { "kind": "skill-contains", "value": "Cratis.Specifications.XUnit.v3" },
+    { "kind": "skill-contains", "value": "<OutputType>Exe</OutputType>" },
+    { "kind": "skill-contains", "value": "running-specs.md" },
+    { "kind": "skill-contains", "value": "[PerFactSpecificationLifecycle]" },
+    { "kind": "skill-contains", "value": "CRSPEC0008" },
     { "kind": "skill-contains", "value": "shared-lifecycle.md" },
     { "kind": "skill-contains", "value": "CRSPEC0001–CRSPEC0007" },
     { "kind": "skill-contains", "value": "Do not suppress these warnings" }

package/package/corpus/skills/filter-syntax/SKILL.md

@@ -80,7 +80,9 @@ dotnet test --filter "Name~LoginTest"
 
 ## MTP filters — xUnit (v3)
 
-xUnit v3 on MTP uses **framework-specific filter flags** instead of the generic `--filter` expression:
+xUnit v3 on MTP uses **framework-specific filter flags** instead of the generic `--filter` expression. A project on `xunit.v3.mtp-off` (the Cratis specification default) runs the native xUnit v3 executable instead and takes `-class`, `-method`, `-namespace`, `-trait` or one `-filter "<query>"`; see the `cratis-specifications-csharp` skill's `references/running-specs.md`.
+
+The flags below apply to the MTP-enabled `xunit.v3` runner:
 
 | Flag | Description |
 |------|-------------|

package/package/corpus/skills/run-tests/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 # Run .NET Tests
 
-Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Specification authoring belongs to **cratis-specifications-csharp**; Cratis core repositories run xUnit v2 on VSTest.
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Specification authoring belongs to **cratis-specifications-csharp**; Cratis spec projects on Specifications 5 and xUnit v3 run as the built executable, not `dotnet test`; see its `references/running-specs.md` for the loop and filter flags. Projects still on xUnit v2 run on VSTest.
 
 Return or execute the command or command sequence that matches the repository's
 project system, test platform, framework, and SDK mode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.103.5",
+  "version": "7.103.7",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [